From 15c3e5bf3f403bb351a88daf5c7407a7bf5ceef2 Mon Sep 17 00:00:00 2001 From: Lan Tian Date: Tue, 14 Jul 2026 17:24:20 +0800 Subject: [PATCH] fix(v2): drop stale extract params (markdown_ref, idempotency_key) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against the live AIDE spec: /v2/extract and /v2/extract/jobs accept only schema / markdown / markdown_url / model / options (+ service_tier) — no markdown_ref, no idempotency_key. Remove both from client.v2.extract / extractJobs.create (mirrors landing-ai/ade-python#111). files.upload remains (/v1/files still in the spec) but its docstring and the README no longer claim it feeds extract as markdown_ref. Also drop idempotency_key from client.v2.workflow / workflowJobs.create — the spec's /v2/workflow* request bodies don't define it either. (ade-python#111 didn't cover workflow because that repo defers the workflow surface; ade-typescript ships it.) No released-surface break: client.v2 is unreleased (added after v2.7.0). Co-Authored-By: Claude Opus 4.8 --- README.md | 12 +----------- src/resources/v2/extract.ts | 8 -------- src/resources/v2/files.ts | 5 ++--- src/resources/v2/v2.ts | 5 ++--- src/resources/v2/workflow.ts | 4 ---- 5 files changed, 5 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 1fc82f74..193bf082 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,7 @@ console.log(response.markdown); #### V2 Extract -Extract structured data from Markdown using a JSON schema. Provide exactly one of `markdown`, `markdown_ref` (from `client.v2.files.upload`), or `markdown_url`. +Extract structured data from Markdown using a JSON schema. Provide exactly one of `markdown` or `markdown_url`. ```ts const response = await client.v2.extract({ @@ -231,16 +231,6 @@ console.log(done.status, done.result); // client.v2.extractJobs.{create,get,list,wait} mirror the same shape for extract jobs. ``` -#### File staging - -`client.v2.files.upload` stages bytes on the ADE data plane and returns a `file_ref` you can pass as `markdown_ref` to extract: - - -```ts -const fileRef = await client.v2.files.upload({ file: fs.createReadStream('doc.md') }); -const result = await client.v2.extract({ schema: { type: 'object' }, markdown_ref: fileRef }); -``` - `client.v2.parse` and `client.v2.extract` also accept `saveTo`, with the same auto-naming behavior as the V1 methods above. #### Workflows (`parse-extract`) diff --git a/src/resources/v2/extract.ts b/src/resources/v2/extract.ts index 98a5c1aa..8a9a6407 100644 --- a/src/resources/v2/extract.ts +++ b/src/resources/v2/extract.ts @@ -24,9 +24,6 @@ export interface V2ExtractParams { /** Markdown content to extract data from. */ markdown?: string | null; - /** A reference (e.g. from a prior parse or `files.upload`) to markdown content. */ - markdown_ref?: string | null; - /** URL to the markdown file to extract data from. */ markdown_url?: string | null; @@ -38,9 +35,6 @@ export interface V2ExtractParams { * prune unsupported fields and continue. Sent as `options.strict`. */ strict?: boolean | null; - - /** An idempotency key for the request. */ - idempotency_key?: string | null; } export interface V2ExtractJobCreateParams extends V2ExtractParams { @@ -55,10 +49,8 @@ export function buildExtractBody(params: V2ExtractJobCreateParams): Record = { schema: coerceSchema(params.schema) }; const entries: Array<[string, unknown]> = [ ['markdown', params.markdown], - ['markdown_ref', params.markdown_ref], ['markdown_url', params.markdown_url], ['model', params.model], - ['idempotency_key', params.idempotency_key], ['service_tier', params.service_tier], ]; for (const [key, value] of entries) { diff --git a/src/resources/v2/files.ts b/src/resources/v2/files.ts index f61e9be3..5c5fb270 100644 --- a/src/resources/v2/files.ts +++ b/src/resources/v2/files.ts @@ -12,9 +12,8 @@ export interface FileUploadParams { export class Files extends V2Resource { /** - * Stage a file's bytes on the ADE data plane and return a `file_ref` string, - * which can be passed as `markdown_ref` to `client.v2.extract` / - * `client.v2.extractJobs.create`. Served on the ADE host under `/v1/files`. + * Stage a file's bytes on the ADE data plane and return a `file_ref` string. + * Served on the ADE host under `/v1/files`. */ async upload(body: FileUploadParams, options?: RequestOptions): Promise { const response = await this._client.post( diff --git a/src/resources/v2/v2.ts b/src/resources/v2/v2.ts index 24b68776..4656a15e 100644 --- a/src/resources/v2/v2.ts +++ b/src/resources/v2/v2.ts @@ -54,9 +54,8 @@ export class V2 extends V2Resource { /** * Extract structured data from markdown synchronously (`POST /v2/extract`, * JSON body). `schema` accepts a JSON-Schema object or a JSON-encoded string. - * Provide exactly one of `markdown`, `markdown_ref`, or `markdown_url`. - * Rejects with `V2SyncTimeoutError` on a 504; use `extractJobs` for - * long-running documents. + * Provide exactly one of `markdown` or `markdown_url`. Rejects with + * `V2SyncTimeoutError` on a 504; use `extractJobs` for long-running documents. */ async extract( body: V2ExtractParams & { saveTo?: string }, diff --git a/src/resources/v2/workflow.ts b/src/resources/v2/workflow.ts index d085136e..db36364c 100644 --- a/src/resources/v2/workflow.ts +++ b/src/resources/v2/workflow.ts @@ -57,8 +57,6 @@ export interface V2WorkflowParams { /** Optional projection map: response field name → `"$output....."`. */ output?: Record | null; - - idempotency_key?: string | null; } export interface V2WorkflowJobCreateParams extends V2WorkflowParams { @@ -101,7 +99,6 @@ export function prepareWorkflowRequest(params: V2WorkflowJobCreateParams): Prepa if (files.length === 0) { const body: Record = { inputs: resolvedInputs, steps: params.steps }; if (params.output != null) body['output'] = params.output; - if (params.idempotency_key != null) body['idempotency_key'] = params.idempotency_key; if (params.service_tier != null) body['service_tier'] = params.service_tier; return { multipart: false, body }; } @@ -112,7 +109,6 @@ export function prepareWorkflowRequest(params: V2WorkflowJobCreateParams): Prepa steps: JSON.stringify(params.steps), }; if (params.output != null) form['output'] = JSON.stringify(params.output); - if (params.idempotency_key != null) form['idempotency_key'] = params.idempotency_key; if (params.service_tier != null) form['service_tier'] = params.service_tier; for (const [name, file] of files) form[name] = file; return { multipart: true, body: form };