@prism-draft/sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# @prism-draft/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed TypeScript client for the PrismDraft API, with webhook verification. It is
+generated from the API's OpenAPI document, so a route that changes shape changes the
+types and the tests fail until the SDK is regenerated.
+
+Runs on any runtime with global `fetch` and Web Crypto. The pack test installs the packed
+tarball and runs a client, a request, a timeout and a webhook signature under Bun and Node
+20, 22 and 24 (Node 20.20, 22.23 and 24.21 were the versions run; `engines` says
+`node >= 20`). It imports nothing from `node:` or `bun:`. A custom `fetch` must honour the
+request's `signal`, which `timeoutMs` and cancellation rely on.
+
+## Install
+
+```sh
+npm install @prism-draft/sdk
+```
+
+## Quick start
+
+`apiKey` is a workspace API key (`pd_live_…`) created in the web app, under Settings, API
+keys. It carries exactly the permissions of its role.
+
+```ts
+import { PrismDraft } from "@prism-draft/sdk";
+
+const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });
+
+const { articles, total } = await pd.articles.list({ workspaceId, status: "PUBLISHED" });
+console.log(`${articles.length} of ${total} published articles`);
+```
+
+The example assumes `workspaceId` is in scope: the id after `/w/` in the web app's address.
+
+## Resources
+
+One property per resource, one method per operation. Each method has `<Resource><Method>Input`
+and `<Resource><Method>Output` types, exported from the package (`ArticlesListInput`).
+
+| Property              | Methods                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pd.articles`         | `create` `list` `duplicate` `get` `update` `delete` `submit` `approve` `reject` `requestChanges` `publish` `unpublish` `transitionTranslations` `listReviews` `listVersions` `getVersion` `getSources` `restoreVersion` `listComments` `addComment` `resolveComment` `reopenComment` `checkDuplicates` `setHeroFromUrl` `setHeroFromFile` `detachHeroFromBody` |
+| `pd.articleGroups`    | `list` `get` `delete` `approve` `publish` `unpublish`                                                                                                                                                                                                                                                                                                          |
+| `pd.categories`       | `list` `create` `update` `delete` `setForArticle` `suggestForArticle` `suggestForProject` `translate`                                                                                                                                                                                                                                                          |
+| `pd.projects`         | `list` `create` `get` `update` `delete` `archive` `restore` `listMembers` `addMember` `setMemberRole` `removeMember`                                                                                                                                                                                                                                           |
+| `pd.generation`       | `estimate` `getOutline` `approveOutline` `aiEdit` `start` `getStatus` `cancel` `regenerateImage` `updateAsset` `deleteAsset`                                                                                                                                                                                                                                   |
+| `pd.translations`     | `estimate` `create`                                                                                                                                                                                                                                                                                                                                            |
+| `pd.webhooks`         | `list` `create` `delete`                                                                                                                                                                                                                                                                                                                                       |
+| `pd.integrations`     | `list` `create` `update` `delete`                                                                                                                                                                                                                                                                                                                              |
+| `pd.knowledge`        | `list` `create` `uploadContent` `reingest` `delete`                                                                                                                                                                                                                                                                                                            |
+| `pd.brandVoices`      | `list` `create` `update` `delete`                                                                                                                                                                                                                                                                                                                              |
+| `pd.contentTemplates` | `list` `create` `update` `delete`                                                                                                                                                                                                                                                                                                                              |
+| `pd.briefs`           | `draft` `list` `create` `get` `update` `delete`                                                                                                                                                                                                                                                                                                                |
+| `pd.ideas`            | `list` `create` `update` `delete` `generate`                                                                                                                                                                                                                                                                                                                   |
+| `pd.calendar`         | `list` `create` `update` `delete`                                                                                                                                                                                                                                                                                                                              |
+| `pd.links`            | `list` `generate` `decide`                                                                                                                                                                                                                                                                                                                                     |
+| `pd.social`           | `generate` `list`                                                                                                                                                                                                                                                                                                                                              |
+| `pd.siteAnalyses`     | `start` `get` `apply`                                                                                                                                                                                                                                                                                                                                          |
+| `pd.dashboard`        | `getAnalytics` `getTrends` `getArticleCounts` `listJobs` `listAudit` `getCreditBurn`                                                                                                                                                                                                                                                                           |
+| `pd.usage`            | `listTransactions` `get` `listPayments` `listQuotas` `setQuota`                                                                                                                                                                                                                                                                                                |
+| `pd.billing`          | `listCreditPackages` `getCredits` `adjustCredits` `listPlans` `getSubscription` `startSubscriptionCheckout` `openPortal` `startCheckout`                                                                                                                                                                                                                       |
+| `pd.workspaces`       | `list` `create` `get` `update` `listMembers` `addMember` `setMemberRoles` `removeMember`                                                                                                                                                                                                                                                                       |
+| `pd.roles`            | `list` `create` `update` `delete` `duplicate`                                                                                                                                                                                                                                                                                                                  |
+| `pd.permissions`      | `list`                                                                                                                                                                                                                                                                                                                                                         |
+| `pd.invitations`      | `list` `revoke` `resend`                                                                                                                                                                                                                                                                                                                                       |
+| `pd.apiKeys`          | `list` `create` `revoke` `rotate`                                                                                                                                                                                                                                                                                                                              |
+| `pd.blog`             | `listPosts` `listCategories` `getPost` `getPostEdit` (PrismDraft's public blog: the first three need no valid key)                                                                                                                                                                                                                                             |
+
+## Documentation
+
+The guides and the reference for every method are at <https://docs.prism-draft.com/sdk>.
+
+- [Authentication](https://docs.prism-draft.com/sdk/guides/authentication): keys, roles, the workspace id, rotation.
+- [Conventions](https://docs.prism-draft.com/sdk/guides/conventions): input, output, pagination, `pd.raw`.
+- [Errors](https://docs.prism-draft.com/sdk/guides/errors): `PrismDraftError` and every error code.
+- [Retries and timeouts](https://docs.prism-draft.com/sdk/guides/retries-and-timeouts)
+- [Uploads](https://docs.prism-draft.com/sdk/guides/uploads)
+- [Webhooks](https://docs.prism-draft.com/sdk/guides/webhooks): verifying a delivery and every event.
+- [Versioning](https://docs.prism-draft.com/sdk/guides/versioning)
+- [Recipes](https://docs.prism-draft.com/sdk/guides/recipes): publish an imported article, sync a site, paginate, bulk-update categories.
+
+The constructor throws a `TypeError` for an empty `apiKey`, so an unset environment
+variable fails at start-up instead of as a 401 later.
+
+## License
+
+`UNLICENSED`: the package is public to install, and no permission is granted to copy or
+redistribute its code. Using it to call the PrismDraft API is what it is for.
+
+## Releasing
+
+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                         # 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         # 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.
+
+## Development
+
+The package exports its TypeScript source inside the workspace (`"exports":
+"./src/index.ts"`) and `dist/` only in the packed tarball.
+
+**What is generated.** `openapi.json` is a snapshot of the API's OpenAPI document,
+filtered to what an API key can use. `src/generated/schema.ts` (types, by
+`openapi-typescript`) and `src/generated/resources.ts` (one class per resource) come
+from it. All three are committed. After any route change:
+
+```sh
+bun run --cwd apps/api openapi:export
+bun run --cwd packages/sdk generate
+```
+
+Two tests fail on a stale file: `apps/api/test/openapi-snapshot.test.ts` (the snapshot
+against the live document) and `packages/sdk/test/generated.test.ts` (the generated
+files against the snapshot).
+
+**Coverage gate.** `test/response-coverage.test.ts` requires every operation in the
+surface to declare a JSON 2xx `response` schema (a 204-only operation is exempt) and an
+`operationId` of the form `resource.method`, unique across the API. The
+`resource` part becomes the class (`articleGroups` is `pd.articleGroups`) and
+`method` the method. `bun run --cwd packages/sdk coverage [Tag …]` lists what is still
+missing, read from the live app, not the snapshot.
+
+**The surface is a denylist.** `scripts/surface.ts` lists `SDK_EXCLUDED_TAGS` and
+`SDK_EXCLUDED_OPERATIONS` (`"METHOD /path"`, each with its reason) and drops every
+`/events` stream and every untagged operation. Everything else is in the SDK by default,
+so a new route needs its `operationId` and response schema or the gate fails. A route
+that cannot be a typed method (a download, a redirect, a person's browser flow) goes on
+the denylist, with a reason; `test/surface.test.ts` checks that every entry still exists.
+
+**To add an operation:** declare `operationId` and the 2xx `response` schema in the
+route, add a test that parses a real answer with that schema (see
+`apps/api/test/sdk-responses-*.test.ts`), run the two commands above, commit the
+regenerated files. A request body the document cannot describe (an upload read by a
+content-type parser) goes in `RAW_BODY_OPERATIONS` in `scripts/generate.ts`.
+
+**`typescript-classic`.** A devDependency, an alias of `typescript@5.9`, used only by
+`scripts/generate.ts`. `openapi-typescript` builds its output with the classic compiler
+API (`ts.factory`), which the workspace's TypeScript 7 (the Go compiler) does not
+have; the generator registers the alias in place of `typescript` before importing it.
+`tsc` everywhere else is still TypeScript 7. It is a devDependency, so it is not in the
+tarball's dependencies.
+
+**Build.** `bun run build` writes `dist/index.js` (one ESM file, not minified, with
+`openapi-fetch` left as an import) and the `.d.ts` files. Three points about
+TypeScript 7:
+
+- Declarations are emitted by `tsc` (`tsconfig.build.json`, `emitDeclarationOnly`), which
+  works, but needs an explicit `rootDir` (TS5011 otherwise).
+- `rewriteRelativeImportExtensions` rewrites `./x.ts` to `./x.js` in emitted JavaScript,
+  not in declarations, which kept the `.ts` specifiers. `scripts/build.ts` rewrites
+  them in `dist/**/*.d.ts` after `tsc` runs. The declarations are still the compiler's.
+- npm and Bun ignore `publishConfig.exports` (pnpm applies it), so a plain `npm pack`
+  would export `./src/index.ts`, which the tarball does not contain. `prepack` and
+  `postpack` (`scripts/pack-manifest.ts`) swap the published `exports` in for the
+  pack and put the workspace form back, and drop `scripts` and `devDependencies`.
+
+`test/pack.test.ts` builds, packs, installs the tarball into an empty project, typechecks a
+consumer and every example in this README and in `docs/guides` with `tsc`, and imports it
+under Bun and Node.

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+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 {
+    /** A workspace API key (`pd_live_…`). Must not be empty. */
+    apiKey: string;
+    /** An absolute `http(s)` URL; default `https://api.prism-draft.com`. */
+    baseUrl?: string;
+    /**
+     * 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;
+    /**
+     * Default for every call: an attempt that takes longer fails with a `PrismDraftTimeoutError`.
+     * Per attempt, so a retried read gets a fresh timer. Unset: no timeout. A finite number above 0;
+     * a call's `init.timeoutMs` overrides it.
+     */
+    timeoutMs?: number;
+    /**
+     * The longest a retry waits, in ms; default 8000. A `Retry-After` above it is not retried
+     * (the answer is returned), so 60000 rides out the API's rate-limit window. A finite number above 0.
+     */
+    maxRetryDelayMs?: number;
+}
+/**
+ * The API client: one property per resource (`pd.articles.list({ workspaceId })`),
+ * and `raw`, the underlying `openapi-fetch` client, for anything the methods do not cover.
+ * Every non-2xx answer throws a `PrismDraftError`.
+ */
+export declare class PrismDraft extends PrismDraftResources {
+    readonly raw: PrismDraftClient;
+    /**
+     * @throws {TypeError} for an empty `apiKey`, a `baseUrl` that is not an absolute http(s) URL,
+     * or a `timeoutMs` or `maxRetryDelayMs` that is not a finite number above 0.
+     */
+    constructor(options: PrismDraftOptions);
+}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/** The API's structured error (spec §71): `{ error: { code, message, details? } }`. */
+export declare class PrismDraftError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+/**
+ * A request that did not finish within `timeoutMs` (the client option or the per-call one).
+ * Not a `PrismDraftError`: the API never answered. A call the caller cancelled with its own
+ * `signal` rejects with that signal's reason instead.
+ */
+export declare class PrismDraftTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** A webhook delivery whose signature is missing, malformed, stale or wrong. */
+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;
+    constructor(event: string);
+}