@prism-draft/sdk 0.0.0-stage → 0.2.0

package/dist/middleware.d.ts

@@ -0,0 +1,15 @@
+import type { Middleware } from "openapi-fetch";
+/** Turns every non-2xx answer into a `PrismDraftError` (decision D5). */
+export declare const throwOnError: Middleware;
+/**
+ * A path value of `""`, `.` or `..` survives URL-encoding and then `new Request`
+ * collapses it as a dot segment, so the call would reach another route (`..` turns
+ * `/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

@@ -0,0 +1,22 @@
+/** 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. */
+    timeoutMs?: number;
+    /** The longest a retry waits; a `Retry-After` above it is not retried. Default 8000. */
+    maxRetryDelayMs?: number;
+    /** Waits `ms`. The wait is abandoned when the caller's `signal` aborts, whether or not this honours it. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** 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: FetchLike, options?: RetryOptions): typeof fetch;

package/dist/transport.d.ts

@@ -0,0 +1,15 @@
+import type { Client } from "openapi-fetch";
+import type { paths } from "./generated/schema.js";
+/** The `openapi-fetch` client over the whole API, which every resource class calls. */
+export type PrismDraftClient = Client<paths>;
+/** What a call takes besides its input. */
+export interface RequestOptions {
+    /** Aborts the request when it fires; an aborted read is not retried. */
+    signal?: AbortSignal;
+    /**
+     * Fails the call with a `PrismDraftTimeoutError` when an attempt takes longer than this many
+     * milliseconds. Per attempt: a retried read gets a fresh timer. Overrides the client's
+     * `timeoutMs`. A finite number above 0.
+     */
+    timeoutMs?: number;
+}

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/webhook-events.d.ts

@@ -0,0 +1,99 @@
+export declare const WEBHOOK_EVENTS: readonly ["article.created", "article.generation.started", "article.generation.completed", "article.generation.failed", "article.approved", "article.rejected", "article.published", "article.updated", "article.unpublished", "image.generated", "image.regenerated", "credits.purchased", "credits.granted", "credits.consumed"];
+export type WebhookEventName = (typeof WEBHOOK_EVENTS)[number];
+export type ArticleChangedField = "title" | "content" | "slug" | "categories" | "metaTitle" | "metaDescription" | "targetKeywords" | "secondaryKeywords";
+interface ArticleSnapshot {
+    articleId: string;
+    workspaceId: string;
+    projectId: string;
+    slug: string;
+    status: string;
+    primaryLanguage: string;
+    translationGroupId: string;
+    title: string;
+}
+export interface WebhookEventData {
+    "article.created": {
+        articleId: string;
+        projectId: string;
+        title: string;
+    };
+    "article.generation.started": {
+        articleId: string;
+        jobId: string;
+        estimatedCredits: number;
+    };
+    "article.generation.completed": {
+        articleId: string;
+        jobId: string;
+        consumedCredits: number;
+    };
+    "article.generation.failed": {
+        articleId: string;
+        jobId: string;
+        error: string;
+    };
+    "article.approved": {
+        articleId: string;
+        reviewId: string;
+        previousStatus: string;
+    };
+    "article.rejected": {
+        articleId: string;
+        reviewId: string;
+        decision: "rejected" | "changes_requested";
+    };
+    "article.published": ArticleSnapshot;
+    "article.updated": ArticleSnapshot & {
+        changed: ArticleChangedField[];
+        /** Present when the slug changed. */
+        previousSlug?: string;
+    };
+    "article.unpublished": ArticleSnapshot & {
+        previousStatus: "PUBLISHED";
+        reason: "status_changed" | "deleted";
+    };
+    "image.generated": {
+        articleId: string;
+        assetId: string;
+        type: "hero" | "inline";
+    };
+    "image.regenerated": {
+        articleId: string;
+        assetId: string;
+        /**
+         * Sent when a hero is replaced by a URL or an upload (`"hero"`). Absent when the
+         * worker regenerates an image in place: that delivery is `articleId` and `assetId`.
+         */
+        type?: "hero" | "inline";
+    };
+    "credits.purchased": {
+        creditAmount: number;
+        stripeEventId: string;
+    };
+    "credits.granted": {
+        creditAmount: number;
+        stripeEventId: string;
+    };
+    "credits.consumed": {
+        articleId: string;
+        jobId: string;
+        credits: number;
+    };
+}
+export type WebhookEvent = {
+    [E in WebhookEventName]: {
+        event: E;
+        data: WebhookEventData[E];
+    };
+}[WebhookEventName];
+export declare const WEBHOOK_EVENT_KEYS: {
+    [E in WebhookEventName]: readonly (keyof WebhookEventData[E])[];
+};
+/**
+ * The keys of `WEBHOOK_EVENT_KEYS` that some emitter leaves out; every other key is
+ * always sent. Pinned against the emitters by `test/webhook-drift.test.ts`.
+ */
+export declare const WEBHOOK_OPTIONAL_KEYS: {
+    [E in WebhookEventName]?: readonly (keyof WebhookEventData[E])[];
+};
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,27 @@
+import { type WebhookEvent } from "./webhook-events.js";
+/** The header a delivery carries its signature in: `t=<unix seconds>,v1=<hex>`. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-prism-draft-signature";
+export interface VerifyInput {
+    /** The string returned when the endpoint was registered, used as is. */
+    secret: string;
+    /** The request body exactly as received. Never JSON.parse and re-stringify it first. */
+    rawBody: string | Uint8Array;
+    signature: string;
+    toleranceSeconds?: number;
+    /** Unix seconds; for tests. */
+    now?: number;
+}
+/**
+ * Whether the delivery is signed with `secret` and recent. Returns `false` for
+ * anything wrong with the delivery (including an empty secret) and throws a
+ * `RangeError` for a `toleranceSeconds` that is not a finite number >= 0, which
+ * is a mistake in the caller's code.
+ */
+export declare function verifyWebhookSignature(input: VerifyInput): Promise<boolean>;
+/**
+ * Verifies a delivery and returns it typed. Throws `WebhookSignatureError` for a
+ * 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,41 @@
 {
   "name": "@prism-draft/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Typed TypeScript client for the PrismDraft API, with webhook verification.",
+  "keywords": [
+    "api-client",
+    "openapi",
+    "prismdraft",
+    "sdk",
+    "webhooks"
+  ],
+  "homepage": "https://docs.prism-draft.com/sdk",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}