@prism-draft/sdk 0.1.0 → 0.2.0

package/README.md

@@ -89,21 +89,46 @@ redistribute its code. Using it to call the PrismDraft API is what it is for.
 
 ## Releasing
 
-Published from `main`, by a maintainer logged in to npm (`npm whoami`) with publish rights
-on the `@prism-draft` scope and a 2FA device.
+Published from `main` by a maintainer who owns or belongs to the `prism-draft` npm
+organisation and has a second factor that npm still accepts.
+
+**One-time setup (done for `argus416`)**
+
+1. Create the organisation `prism-draft` at <https://www.npmjs.com/org/create> (the free
+   plan covers public packages). The scope `@prism-draft` exists only after this; before
+   it, `npm publish` fails with `Scope not found`.
+2. Enable two-factor authentication on the publishing account, set to "Authorization and
+   publishing". npm no longer accepts new authenticator-app (TOTP) enrolments
+   (`Adding a new TOTP 2FA is no longer supported`): add a passkey or security key at
+   `https://npmjs.com/settings/<user>/tfa`. Touch ID through the browser's passkey prompt is
+   enough. Without 2FA the registry answers `403 Two-factor authentication or granular access
+token with bypass 2fa enabled is required to publish packages`.
+3. Log in: `npm login`, then check `npm whoami` and `npm org ls prism-draft`.
+
+Tokens that bypass 2FA are being restricted by npm, so do not build the release around one.
+
+**Each release**
 
 ```sh
 git switch main && git pull
 # bump "version" in packages/sdk/package.json (0.x: minor for new API surface or
 # SDK changes, patch for fixes), commit it, and merge it through a pull request
-bun install
+bun install                         # a stale install fails the build: "Cannot find module 'openapi-fetch'"
 bun run --cwd apps/api openapi:export && bun run --cwd packages/sdk generate   # must leave no diff
 cd packages/sdk && bun --env-file=../../.env test
-npm publish --dry-run              # `prepublishOnly` builds; check the file list: dist/, README, package.json
-npm publish --access public        # asks for the 2FA code
+npm publish --dry-run               # `prepublishOnly` builds; check the file list: dist/, README, package.json
+npm publish --access public         # prints a URL; approve it with the passkey
 git tag sdk-v<version> && git push origin sdk-v<version>
 ```
 
+`bun publish --dry-run --access public` produces the same 14-file tarball (Bun 1.4.2 runs
+`prepublishOnly`, `prepack` and `postpack`). Use `npm publish` for the real release: its
+passkey approval flow is the one that has been exercised.
+
+Afterwards, check `npm view @prism-draft/sdk version` and install it in an empty directory
+(`bun add @prism-draft/sdk`, then import `PrismDraft`). The registry can take a minute to
+show a new version.
+
 A published version cannot be replaced. Fix forward with a patch release; `npm deprecate`
 marks a bad one.
 

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { PrismDraftResources } from "./generated/resources.js";
+import { type FetchLike } from "./retry.js";
 import type { PrismDraftClient } from "./transport.js";
 export declare const DEFAULT_BASE_URL = "https://api.prism-draft.com";
 export interface PrismDraftOptions {
@@ -6,7 +7,17 @@ export interface PrismDraftOptions {
     apiKey: string;
     /** An absolute `http(s)` URL; default `https://api.prism-draft.com`. */
     baseUrl?: string;
-    fetch?: typeof fetch;
+    /**
+     * Replaces the global `fetch`. A plain function is enough (no `preconnect`, which Bun's
+     * `typeof fetch` requires); the SDK calls it with a `Request`, and with `requestInit` after it.
+     */
+    fetch?: FetchLike;
+    /**
+     * Passed as the second argument of every `fetch` call, retries included: `{ cache: "no-store" }`
+     * for Next.js, a `dispatcher` for undici. `body`, `method`, `headers` and `signal` belong to
+     * the client and are ignored if present.
+     */
+    requestInit?: Omit<RequestInit, "body" | "method" | "headers" | "signal">;
     /** Retries for GET/HEAD on network errors and 429/502/503/504. Default 2; 0 disables. */
     maxRetries?: number;
     /**

package/dist/errors.d.ts

@@ -18,6 +18,16 @@ export declare class PrismDraftTimeoutError extends Error {
 export declare class WebhookSignatureError extends Error {
     constructor(message?: string);
 }
+/**
+ * A delivery with a valid signature whose body is not what the API sends: `reason` is `not_json`
+ * or `not_envelope` (JSON, but not `{ event, data }`). A `WebhookSignatureError` too, so a caller
+ * that catches that class keeps working; test for this class first to answer 400 here and 401 for
+ * the plain signature error.
+ */
+export declare class WebhookPayloadError extends WebhookSignatureError {
+    readonly reason: "not_json" | "not_envelope";
+    constructor(reason: WebhookPayloadError["reason"], message: string);
+}
 /** A signed delivery for an event this SDK version does not know. Answer 2xx and ignore it. */
 export declare class UnknownWebhookEventError extends Error {
     readonly event: string;

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { DEFAULT_BASE_URL, PrismDraft, type PrismDraftOptions } from "./client.js";
 export type { PrismDraftClient, RequestOptions } from "./transport.js";
+export type { Article, ArticleStatus, ArticleVersion, Category } from "./types.js";
 export * from "./generated/resources.js";
 export type { paths, components, operations } from "./generated/schema.js";
-export { PrismDraftError, PrismDraftTimeoutError, UnknownWebhookEventError, WebhookSignatureError, } from "./errors.js";
+export { PrismDraftError, PrismDraftTimeoutError, UnknownWebhookEventError, WebhookPayloadError, WebhookSignatureError, } from "./errors.js";
 export { throwOnError } from "./middleware.js";
-export { retryingFetch, type RetryOptions } from "./retry.js";
+export { retryingFetch, type FetchLike, type RetryOptions } from "./retry.js";
 export { WEBHOOK_SIGNATURE_HEADER, constructWebhookEvent, verifyWebhookSignature, type VerifyInput, } from "./webhooks.js";
 export { WEBHOOK_EVENTS, type ArticleChangedField, type WebhookEvent, type WebhookEventData, type WebhookEventName, } from "./webhook-events.js";

package/dist/index.js

@@ -1530,6 +1530,15 @@ class WebhookSignatureError extends Error {
   }
 }
 
+class WebhookPayloadError extends WebhookSignatureError {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "WebhookPayloadError";
+    this.reason = reason;
+  }
+}
+
 class UnknownWebhookEventError extends Error {
   event;
   constructor(event) {
@@ -1569,6 +1578,21 @@ var rejectUnsafePathParams = {
     return;
   }
 };
+var rejectNonJsonBody = {
+  async onResponse({ response }) {
+    if (!response.ok)
+      return;
+    const text = await response.clone().text();
+    if (text.length === 0)
+      return;
+    try {
+      JSON.parse(text);
+    } catch {
+      throw new PrismDraftError(response.status, "INVALID_RESPONSE", "The API returned a non-JSON body");
+    }
+    return;
+  }
+};
 
 // src/retry.ts
 var RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
@@ -1613,6 +1637,34 @@ function wait(sleep, ms, signal) {
     sleep(ms, signal).then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
   });
 }
+function releaseWhenSettled(response, release) {
+  if (response.body === null) {
+    release();
+    return response;
+  }
+  const reader = response.body.getReader();
+  const body = new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          release();
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      } catch (error) {
+        release();
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      release();
+      return reader.cancel(reason);
+    }
+  });
+  return new Response(body, response);
+}
 function retryingFetch(inner, options = {}) {
   const maxRetries = options.maxRetries ?? 2;
   const sleep = options.sleep ?? defaultSleep;
@@ -1635,20 +1687,27 @@ function retryingFetch(inner, options = {}) {
         timeout = expiry;
         timer = setTimeout(() => expiry.abort(new PrismDraftTimeoutError(timeoutMs)), Math.min(timeoutMs, MAX_TIMER_MS));
         timer.unref?.();
-        request = new Request(request, { signal: anySignal([input.signal, expiry.signal]) });
+        try {
+          request = new Request(request, { signal: anySignal([input.signal, expiry.signal]) });
+        } catch (error) {
+          clearTimeout(timer);
+          throw error;
+        }
       }
+      const release = () => clearTimeout(timer);
       const backoff = Math.min(BASE_WAIT_MS * 2 ** attempt, maxDelay);
       let delay;
       try {
         const response = await inner(request);
         if (!idempotent || !RETRYABLE_STATUS.has(response.status) || attempt >= maxRetries) {
-          return response;
+          return releaseWhenSettled(response, release);
         }
         const asked = retryAfterMs(response);
         if (asked !== undefined && asked > maxDelay)
-          return response;
-        if (response.status === 429 && asked === undefined)
-          return response;
+          return releaseWhenSettled(response, release);
+        if (response.status === 429 && asked === undefined) {
+          return releaseWhenSettled(response, release);
+        }
         delay = asked ?? backoff;
       } catch (error) {
         clearTimeout(timer);
@@ -1675,6 +1734,15 @@ function isHttpUrl(value) {
     return false;
   }
 }
+var RESERVED_INIT_KEYS = ["body", "method", "headers", "signal"];
+function withRequestInit(inner, requestInit) {
+  if (requestInit === undefined)
+    return inner;
+  const init = { ...requestInit };
+  for (const key of RESERVED_INIT_KEYS)
+    delete init[key];
+  return (input) => inner(input, init);
+}
 
 class PrismDraft extends PrismDraftResources {
   raw;
@@ -1689,13 +1757,13 @@ class PrismDraft extends PrismDraftResources {
     const raw = createOpenApiClient({
       baseUrl,
       headers: { authorization: `Bearer ${options.apiKey}` },
-      fetch: retryingFetch(options.fetch ?? fetch, {
+      fetch: retryingFetch(withRequestInit(options.fetch ?? fetch, options.requestInit), {
         maxRetries: options.maxRetries ?? 2,
         timeoutMs: options.timeoutMs,
         maxRetryDelayMs: options.maxRetryDelayMs
       })
     });
-    raw.use(rejectUnsafePathParams, throwOnError);
+    raw.use(rejectUnsafePathParams, throwOnError, rejectNonJsonBody);
     super(raw);
     this.raw = raw;
   }
@@ -1803,11 +1871,11 @@ async function constructWebhookEvent(input) {
   try {
     envelope = JSON.parse(text);
   } catch {
-    throw new WebhookSignatureError("The webhook body is not JSON");
+    throw new WebhookPayloadError("not_json", "The webhook body is not JSON");
   }
   const { event, data } = envelope ?? {};
   if (typeof event !== "string" || typeof data !== "object" || data === null) {
-    throw new WebhookSignatureError("The webhook body is not an { event, data } envelope");
+    throw new WebhookPayloadError("not_envelope", "The webhook body is not an { event, data } envelope");
   }
   if (!WEBHOOK_EVENTS.includes(event)) {
     throw new UnknownWebhookEventError(event);
@@ -1847,6 +1915,7 @@ export {
   Usage,
   WEBHOOK_EVENTS,
   WEBHOOK_SIGNATURE_HEADER,
+  WebhookPayloadError,
   WebhookSignatureError,
   Webhooks,
   Workspaces,

package/dist/middleware.d.ts

@@ -7,3 +7,9 @@ export declare const throwOnError: Middleware;
  * `/api/articles/..` into `/api/`). It is refused before any request is made.
  */
 export declare const rejectUnsafePathParams: Middleware;
+/**
+ * A 2xx answer whose body is not JSON (an HTML error page from a proxy, say) becomes a
+ * `PrismDraftError`; `openapi-fetch` would throw a bare `SyntaxError`. The message carries
+ * neither the body nor the URL.
+ */
+export declare const rejectNonJsonBody: Middleware;

package/dist/retry.d.ts

@@ -1,5 +1,12 @@
 /** The default for `maxRetryDelayMs`. A server that asks for more is not retried: see `retryAfterMs`. */
 export declare const DEFAULT_MAX_RETRY_DELAY_MS = 8000;
+/**
+ * What the client needs of `fetch`: a call with a `Request`, `URL` or string and optional init.
+ * Looser than `typeof fetch`, which under Bun's types also demands `preconnect`, so a plain
+ * wrapper function is accepted without a cast. The SDK itself only calls `fetch(request)`
+ * (and `fetch(request, requestInit)` when the client has a `requestInit`).
+ */
+export type FetchLike = (input: Request | URL | string, init?: RequestInit) => Promise<Response>;
 export interface RetryOptions {
     maxRetries?: number;
     /** Fails an attempt after this many ms with a `PrismDraftTimeoutError`; a request's own `timeoutMs` overrides it. Unset: none. */
@@ -12,4 +19,4 @@ export interface RetryOptions {
 /** One signal that aborts with the reason of whichever of `signals` aborts first. */
 export declare function anySignal(signals: AbortSignal[]): AbortSignal;
 /** Retries idempotent reads only; a write that may have landed is never replayed (decision D6). */
-export declare function retryingFetch(inner: typeof fetch, options?: RetryOptions): typeof fetch;
+export declare function retryingFetch(inner: FetchLike, options?: RetryOptions): typeof fetch;

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+import type { ArticlesGetOutput, ArticlesListOutput } from "./generated/resources.js";
+/** An article as `articles.list` returns it. */
+export type Article = ArticlesListOutput["articles"][number];
+/** `DRAFT`, `QUEUED`, `PROCESSING`, `NEEDS_REVIEW`, `CHANGES_REQUESTED`, `APPROVED` or `PUBLISHED`. */
+export type ArticleStatus = Article["status"];
+/** A category as it is embedded in an article of `articles.list`. */
+export type Category = Article["categories"][number];
+/** A language version of an article, as listed under `translations.versions` by `articles.get`. */
+export type ArticleVersion = ArticlesGetOutput["translations"]["versions"][number];

package/dist/webhooks.d.ts

@@ -20,8 +20,8 @@ export interface VerifyInput {
 export declare function verifyWebhookSignature(input: VerifyInput): Promise<boolean>;
 /**
  * Verifies a delivery and returns it typed. Throws `WebhookSignatureError` for a
- * bad signature or a body that is not `{ event, data }`, and
- * `UnknownWebhookEventError` for an event this version does not know: answer 2xx
- * to that one, or the API retries it.
+ * bad or stale signature, `WebhookPayloadError` (a subclass of it) for a signed body that is
+ * not JSON or not `{ event, data }`, and `UnknownWebhookEventError` for an event this version
+ * does not know: answer 2xx to that one, or the API retries it.
  */
 export declare function constructWebhookEvent(input: VerifyInput): Promise<WebhookEvent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prism-draft/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed TypeScript client for the PrismDraft API, with webhook verification.",
   "keywords": [
     "api-client",