@forumulate/sdk 0.12.0 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,14 @@
3
3
  Releases of `@forumulate/sdk`. Earlier versions are described in the git history of
4
4
  `packages/sdk` (`release(sdk): …` commits).
5
5
 
6
+ ## 0.12.1
7
+
8
+ - A CSV export over the API's row threshold answers `202` with a job instead of the
9
+ file. Every `exportCsv` (and any GET that answers 202 with an `export.csv` job) now
10
+ waits for the job and returns the file, the same as the `200`; a failed job throws
11
+ `ForumulateError` with the job's error, and 30 minutes without a result throws
12
+ `export.timeout`. Pass `raw: true` to get the `202` itself.
13
+
6
14
  ## 0.12.0
7
15
 
8
16
  Types and operations for the 2026-11-01 batch: connector `knowledge` state and the token
package/dist/http.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * and not another.
7
7
  */
8
8
  /** Kept in step with package.json by `coverage.test.ts`. */
9
- export declare const SDK_VERSION = "0.12.0";
9
+ export declare const SDK_VERSION = "0.12.1";
10
10
  /** The API's error envelope: `{ error: { code, message, details? }, requestId? }`. */
11
11
  export interface ForumulateErrorInit {
12
12
  /** Field-level detail, e.g. `{ title: ['Required'] }` for `validation.failed`. */
@@ -83,4 +83,6 @@ export interface Transport {
83
83
  */
84
84
  export declare function retryDelayMs(attempt: number, retryAfter: string | null | undefined, now?: number): number | null;
85
85
  export declare function send<T>(t: Transport, init: SendInit): Promise<T>;
86
+ /** How long a queued export is waited for before giving up (the file is kept 7 days). */
87
+ export declare const EXPORT_WAIT_MS: number;
86
88
  //# sourceMappingURL=http.d.ts.map
package/dist/http.js CHANGED
@@ -7,11 +7,11 @@
7
7
  * and not another.
8
8
  */
9
9
  Object.defineProperty(exports, "__esModule", { value: true });
10
- exports.ForumulateError = exports.SDK_VERSION = void 0;
10
+ exports.EXPORT_WAIT_MS = exports.ForumulateError = exports.SDK_VERSION = void 0;
11
11
  exports.retryDelayMs = retryDelayMs;
12
12
  exports.send = send;
13
13
  /** Kept in step with package.json by `coverage.test.ts`. */
14
- exports.SDK_VERSION = '0.12.0';
14
+ exports.SDK_VERSION = '0.12.1';
15
15
  /**
16
16
  * Thrown for any non-2xx API response, and for a network failure that
17
17
  * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the
@@ -184,8 +184,15 @@ async function send(t, init) {
184
184
  await sleep(wait, init.signal);
185
185
  continue;
186
186
  }
187
- if (res.ok)
187
+ if (res.ok) {
188
+ if (res.status === 202 && method === 'GET' && !init.raw && init.kind !== 'binary') {
189
+ const job = (await decode(res, { ...init, kind: 'json' }));
190
+ if (job?.kind === 'export.csv' && job.links?.self)
191
+ return (await followExport(t, init, job));
192
+ return job;
193
+ }
188
194
  return (await decode(res, init));
195
+ }
189
196
  if (attempt < maxRetries && RETRY_STATUS.has(res.status)) {
190
197
  const wait = retryDelayMs(attempt, res.headers?.get?.('retry-after'));
191
198
  if (wait !== null) {
@@ -197,4 +204,32 @@ async function send(t, init) {
197
204
  throw await toError(res);
198
205
  }
199
206
  }
207
+ /** An absolute or `/api`-prefixed link from the API, as a path under the client's base URL. */
208
+ const apiPath = (link) => link.replace(/^https?:\/\/[^/]+/, '').replace(/^\/api(?=\/)/, '');
209
+ /** How long a queued export is waited for before giving up (the file is kept 7 days). */
210
+ exports.EXPORT_WAIT_MS = 30 * 60_000;
211
+ /**
212
+ * A CSV export over the API's row threshold answers 202 with the job that builds
213
+ * the file, not the file. Every caller asked for the file, so wait for the job and
214
+ * fetch it: the same answer the 200 gives, however big. `raw: true` opts out.
215
+ */
216
+ async function followExport(t, init, first) {
217
+ const base = { headers: init.headers, signal: init.signal, version: init.version, maxRetries: init.maxRetries };
218
+ const deadline = Date.now() + exports.EXPORT_WAIT_MS;
219
+ let job = first;
220
+ for (let i = 0; job.state !== 'completed'; i++) {
221
+ if (job.state === 'failed' || job.state === 'canceled') {
222
+ throw new ForumulateError(500, job.error?.code ?? 'job.failed', job.error?.message ?? 'The export failed.', { body: job });
223
+ }
224
+ if (Date.now() > deadline) {
225
+ throw new ForumulateError(504, 'export.timeout', 'The export did not finish within 30 minutes.', { body: job });
226
+ }
227
+ await sleep(Math.min(1000 * 2 ** i, 10_000), init.signal);
228
+ job = await send(t, { ...base, method: 'GET', path: apiPath(job.links.self) });
229
+ }
230
+ const result = job.links?.result;
231
+ if (!result)
232
+ throw new ForumulateError(500, 'job.no_result', 'The export finished without a file.', { body: job });
233
+ return send(t, { ...base, method: 'GET', path: apiPath(result), kind: init.kind });
234
+ }
200
235
  //# sourceMappingURL=http.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forumulate/sdk",
3
- "version": "0.12.0",
3
+ "version": "0.12.1",
4
4
  "description": "Typed TypeScript client for the Forumulate REST API.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://forumulate.com/reference",