@forumulate/sdk 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Releases of `@forumulate/sdk`. Earlier versions are described in the git history of
+`packages/sdk` (`release(sdk): …` commits).
+
+## 0.10.0 (unreleased)
+
+Cache, trash and destroy under their own names; publish runs; the token, named.
+
+### Added
+
+- `client.cache.purge({ orgId, space?, page? })` and the generated `cache.purgePage`,
+  `cache.purgeSpace`, `cache.purgeOrg` (`Cache_*`): drop cached copies — our web tier and
+  every CDN the org configured — and answer which addresses went and which `edge` took them
+  (`none` when no CDN fronts them). Nothing is deleted.
+- `cache.providers.*` (`EdgeProvider_*`): configure Fastly, Bunny, KeyCDN or a signed purge
+  webhook beside Cloudflare.
+- `spaces.destroy()` / `pages.destroy()` (`Space_destroy`, `Page_destroy`): delete a TRASHED
+  space or page for good, with `confirm: '<slug>'`. `spaces.purge()` / `pages.purge()` remain
+  as deprecated names; from `Forumulate-Version: 2027-01-01` they require `confirm` too.
+- `pages.publishRuns.*` (`PublishRun_*`): report, list and read docs-as-code runs, and
+  `syncState` — which pages were edited since the last sync, by whom and when.
+- `pages.publish()` takes `purge: 'page' | 'space' | 'none'` and `syncBaseline`, and answers
+  `purged`. `auth.me()` names the token: `id`, `name`, `last4`, `expiresAt`, `capabilities`,
+  `constraints`.
+- Webhook event `publish.completed`.
+
+### Deprecated
+
+- `privacy.consent.purgeSpace()` / `purgeOrg()`: use `cache.purge()`.
+
+## 0.9.0
+
+The policy acceptance gate, from your server.
+
+### Added
+
+- `client.policies`: `status`, `accept`, `claim`, `ticket`, `verify`, `acceptances`, `export`,
+  `erase`, `list` (Forumulate policy feed v1, signed with a link secret or public) and `release`
+  (one exact published version).
+- `verifyAcceptanceToken(token, { keys | secret | jwks | jwksUrl, subject?, spaceId?, orgId?,
+  requireSatisfied? })`: offline verification of the gate's acceptance tokens and receipts
+  (HS256 JWT, `kid`-selected keyring, so a key rotation never breaks a token in flight). Refuses a
+  ticket presented as an acceptance (`wrong_use`), `alg` other than HS256, and expired tokens.
+- `signPolicyTicket`, `policyGatePageUrl` and `readPolicyReturn`: the hosted acceptance page round
+  trip with no API call. `verifyPolicyTicket` checks a ticket of yours that comes back to your
+  server (a bridge between an auth platform's redirect and the hosted page). `parsePolicyGateKeys` reads `FORUMULATE_POLICY_GATE_KEYS`;
+  `policyEmailHash` and `policySha256Hex` are the gate's two hashes.
+- `acceptanceItemsFrom(status, { presentation })`: the items to record after your own UI showed
+  the policies.
+- Forumulate policy feed v1 protocol: `signPolicyFeedRequest` / `verifyPolicyFeedRequest`
+  (`forumulate-*` or `atlas-*` headers, millisecond timestamps, rotation, replay hook) and
+  `verifyPolicyWebhook` / `signPolicyWebhook` (Standard Webhooks, `whsec_` secrets) for
+  `policy.published` and `policy.retired`.
+
+Not published to npm yet: publishing is the integrator's release step.

package/README.md

@@ -192,6 +192,45 @@ const es = await client.translations.get(orgId, spaceId, pageId, 'es'); // { tit
 await client.translations.put(orgId, spaceId, pageId, 'es', { markdown: '…', published: true });
 ```
 
+### 7. Gate sign-up and sign-in on your published policies
+
+`client.policies` and three standalone functions are the server half of the
+[policy acceptance gate](https://forumulate.com/guides/policy-acceptance-gate): your Legal space's
+published Terms, Privacy Policy and so on, accepted by your users in any app, whatever signs them in.
+
+```ts
+import { ForumulateClient, signPolicyTicket, verifyAcceptanceToken, policyGatePageUrl } from '@forumulate/sdk';
+
+const client = ForumulateClient.fromEnv();
+const space = { orgId: process.env.FORUMULATE_ORG!, spaceId: process.env.FORUMULATE_LEGAL_SPACE! };
+
+// What does this user still have to accept before signing in?
+const status = await client.policies.status({ ...space, subject: user.id, event: 'sign_in' });
+
+if (!status.satisfied) {
+  // Send them to the hosted acceptance page with a ticket you sign yourself (no API call).
+  const ticket = await signPolicyTicket(
+    { ...space, subject: user.id, event: 'sign_in', returnUrl: 'https://app.example.com/policy/return' },
+    process.env.FORUMULATE_POLICY_GATE_KEYS!, // "pgk_…:pgs_…"
+  );
+  return redirect(policyGatePageUrl({ ...space, ticket }));
+}
+
+// On the way back (or from the widget): verify the acceptance token offline, with key rotation.
+const r = await verifyAcceptanceToken(token, {
+  keys: process.env.FORUMULATE_POLICY_GATE_KEYS,
+  subject: user.id,
+  requireSatisfied: true,
+});
+```
+
+Also `client.policies.accept` / `claim` / `verify` / `acceptances` / `export` / `erase`, and
+`client.policies.list({ spaceId, secret })` to read Forumulate policy feed v1.
+`verifyPolicyWebhook(headers, rawBody, secret)` checks a `policy.published` / `policy.retired`
+notice, and `signPolicyFeedRequest` / `verifyPolicyFeedRequest` implement the feed's request
+signing, so any platform can consume the feed or serve its own. Recipes for Auth0, Clerk, Supabase,
+Firebase, Auth.js and a custom backend: [Policy gate recipes](https://forumulate.com/guides/policy-gate-recipes).
+
 ## Every endpoint: `typed()`
 
 The helpers above cover the common paths. `typed(method, path, init)` covers every route in the OpenAPI spec, with the path, params, query, body and response all inferred, and autocomplete on path and method:

package/dist/cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `client.cache.purge()` — drop cached copies, delete nothing (FMU-B04).
+ *
+ * The generated `cache.purgeSpace / purgePage / purgeOrg` are the three
+ * operations; this is the one call a deploy script wants: name the space (and
+ * a page, or neither for the whole org) and get back which addresses went and
+ * which CDN took them. The old `privacy.consent.purgeSpace()` still works and
+ * runs the same purge. Destroying a trashed page or space is
+ * `pages.destroy()` / `spaces.destroy()` — a different word on purpose.
+ */
+export interface CachePurgeResult {
+    /** `page`, `space` or `org`. */
+    purged: string;
+    urls: string[];
+    urlCount: number;
+    /** The CDN that took it (`cloudflare`, `fastly`, …), `multiple`, or `none` when none fronts it. */
+    edge: string;
+    edges: {
+        name: string;
+        account: 'platform' | 'org';
+        urls: number;
+        ok: boolean;
+        error?: string;
+    }[];
+    /** Our own web tier was refreshed. */
+    webTier: boolean;
+}
+export interface CachePurgeArgs {
+    orgId: string;
+    /** Space id (or slug where the API accepts one). Omit for the whole organization. */
+    space?: string;
+    /** Page id within `space`: just that page. */
+    page?: string;
+}
+type Http = <T>(method: string, path: string) => Promise<T>;
+export declare function cacheApi(http: Http): {
+    /** `Cache_purgePage`: one page's every address. */
+    purgePage(args: {
+        orgId: string;
+        spaceId: string;
+        pageId: string;
+    }): Promise<CachePurgeResult>;
+    /** `Cache_purgeSpace`: everything under the space. */
+    purgeSpace(args: {
+        orgId: string;
+        spaceId: string;
+    }): Promise<CachePurgeResult>;
+    /** `Cache_purgeOrg`: every space in the organization. */
+    purgeOrg(args: {
+        orgId: string;
+    }): Promise<CachePurgeResult>;
+    /** Purge one page, one space, or (no `space`) every space in the org. */
+    purge(args: CachePurgeArgs): Promise<CachePurgeResult>;
+};
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheApi = cacheApi;
+function cacheApi(http) {
+    const space = (orgId, spaceId) => `/orgs/${encodeURIComponent(orgId)}/spaces/${encodeURIComponent(spaceId)}`;
+    return {
+        /** `Cache_purgePage`: one page's every address. */
+        purgePage(args) {
+            return http('POST', `${space(args.orgId, args.spaceId)}/pages/${encodeURIComponent(args.pageId)}/cache/purge`);
+        },
+        /** `Cache_purgeSpace`: everything under the space. */
+        purgeSpace(args) {
+            return http('POST', `${space(args.orgId, args.spaceId)}/cache/purge`);
+        },
+        /** `Cache_purgeOrg`: every space in the organization. */
+        purgeOrg(args) {
+            return http('POST', `/orgs/${encodeURIComponent(args.orgId)}/cache/purge`);
+        },
+        /** Purge one page, one space, or (no `space`) every space in the org. */
+        purge(args) {
+            const org = encodeURIComponent(args.orgId);
+            if (!args.space) {
+                if (args.page)
+                    throw new Error('cache.purge: `page` needs `space`.');
+                return http('POST', `/orgs/${org}/cache/purge`);
+            }
+            const space = `/orgs/${org}/spaces/${encodeURIComponent(args.space)}`;
+            return http('POST', args.page
+                ? `${space}/pages/${encodeURIComponent(args.page)}/cache/purge`
+                : `${space}/cache/purge`);
+        },
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/http.d.ts

@@ -6,7 +6,7 @@
  * and not another.
  */
 /** Kept in step with package.json by `coverage.test.ts`. */
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.10.0";
 /** The API's error envelope: `{ error: { code, message, details? }, requestId? }`. */
 export interface ForumulateErrorInit {
     /** Field-level detail, e.g. `{ title: ['Required'] }` for `validation.failed`. */

package/dist/http.js

@@ -11,7 +11,7 @@ exports.ForumulateError = exports.SDK_VERSION = void 0;
 exports.retryDelayMs = retryDelayMs;
 exports.send = send;
 /** Kept in step with package.json by `coverage.test.ts`. */
-exports.SDK_VERSION = '0.7.0';
+exports.SDK_VERSION = '0.10.0';
 /**
  * Thrown for any non-2xx API response, and for a network failure that
  * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the

package/dist/index.d.ts

@@ -2,6 +2,11 @@ export * from './types';
 export { verifyWebhookSignature, constructWebhookEvent, type VerifyWebhookInput } from './webhooks';
 export * from './content';
 export * from './translations';
+export * from './policies';
+export * from './cache';
+export * from './policy-tokens';
+export * from './policy-tickets';
+export * from './policy-feed';
 export type { paths, operations } from './schema';
 export type { HttpMethod, MethodsOf, OperationOf, TypedRequestInit, TypedResponse } from './typed';
 export { ForumulateError, SDK_VERSION, retryDelayMs, type CallOptions, type ForumulateErrorInit, } from './http';
@@ -10,6 +15,7 @@ export type { Namespace, NamespaceName, OperationArgs, OperationFn, OperationId,
 export { API_VERSION } from './operations.gen';
 import type { paths } from './schema';
 import type { HttpMethod, TypedRequestInit, TypedResponse } from './typed';
+import { cacheApi } from './cache';
 import { type Query } from './http';
 import { type PositionalHelpers } from './helpers';
 import { type Merged, type Namespace, type OperationArgs, type OptionalArgsOperationId, type OperationId, type OperationReturn, type OperationRow, type PagedOperationId, type Resources } from './resources';
@@ -62,7 +68,7 @@ export interface ForumulateClientOptions {
      */
     userAgent?: string;
 }
-type HandWritten = keyof PositionalHelpers | 'content';
+type HandWritten = keyof PositionalHelpers | 'content' | 'policies' | 'cache';
 /**
  * Typed client for the Forumulate REST API.
  *
@@ -488,6 +494,81 @@ export declare class ForumulateClient {
             }>;
         };
     };
+    /** The policy acceptance gate: status, accept, claim, verify, the feed — see ./policies. */
+    readonly policies: {
+        status: (input: import("./policies").PolicyStatusInput) => Promise<import("./policies").PolicyGateStatus>;
+        accept: (input: import("./policies").PolicyAcceptInput) => Promise<import("./policies").PolicyAcceptanceResult>;
+        claim: (input: import("./policies").PolicyGateSpace & import("./policies").PolicySubjectIdentity & {
+            receipt: string;
+            subject: string;
+        }) => Promise<import("./policies").PolicyAcceptanceResult>;
+        ticket: (input: import("./policies").PolicyGateSpace & import("./policies").PolicySubjectIdentity & {
+            subject: string;
+            event: import("./policy-tokens").PolicyGateEvent;
+            sourceApp?: string;
+            returnUrl?: string;
+            state?: string;
+            locale?: string;
+            ttlSeconds?: number;
+        }) => Promise<{
+            ticket: string;
+            expiresAt: string;
+            pageUrl: string;
+        }>;
+        verify: (input: import("./policies").PolicyGateSpace & {
+            token: string;
+            subject?: string;
+        }) => Promise<{
+            valid: boolean;
+            reason?: string;
+            claims?: Record<string, unknown>;
+        }>;
+        acceptances: (input: import("./policies").PolicyGateSpace & import("./policies").PolicySubjectIdentity & {
+            subject?: string;
+            key?: string;
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            acceptances: import("./policies").PolicyAcceptanceRow[];
+            page: {
+                limit: number;
+                hasMore: boolean;
+                nextCursor: string | null;
+            };
+        }>;
+        export: (input: import("./policies").PolicyGateSpace & {
+            format: "csv" | "json";
+            subject?: string;
+            emailHash?: string;
+            key?: string;
+        }) => Promise<string>;
+        erase: (input: {
+            orgId: string;
+        } & import("./policies").PolicySubjectIdentity & {
+            subject?: string;
+        }) => Promise<{
+            erased: number;
+        }>;
+        list: (input: import("./policies").PolicyListInput) => Promise<import("./policy-feed").PolicyFeedList>;
+        release: (input: {
+            orgId: string;
+            key: string;
+            version: string;
+        }) => Promise<{
+            release: {
+                kind: string;
+                version: string;
+                title: string;
+                contentHtml: string;
+                contentSha256: string;
+                publishedAt: string;
+                effectiveAt: string;
+                changeNote: string | null;
+            };
+        }>;
+    };
+    /** `cache.purge({ orgId, space, page })` over the generated `Cache_*` methods (FMU-B04). */
+    readonly cache: ReturnType<typeof cacheApi>;
     readonly orgs: Merged<Namespace<"orgs">, {
         list: () => Promise<{
             orgs: import("./types").Organization[];

package/dist/index.js

@@ -21,6 +21,11 @@ Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get
 Object.defineProperty(exports, "constructWebhookEvent", { enumerable: true, get: function () { return webhooks_1.constructWebhookEvent; } });
 __exportStar(require("./content"), exports);
 __exportStar(require("./translations"), exports);
+__exportStar(require("./policies"), exports);
+__exportStar(require("./cache"), exports);
+__exportStar(require("./policy-tokens"), exports);
+__exportStar(require("./policy-tickets"), exports);
+__exportStar(require("./policy-feed"), exports);
 var http_1 = require("./http");
 Object.defineProperty(exports, "ForumulateError", { enumerable: true, get: function () { return http_1.ForumulateError; } });
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return http_1.SDK_VERSION; } });
@@ -31,6 +36,8 @@ var operations_gen_1 = require("./operations.gen");
 Object.defineProperty(exports, "API_VERSION", { enumerable: true, get: function () { return operations_gen_1.API_VERSION; } });
 const content_1 = require("./content");
 const translations_1 = require("./translations");
+const policies_1 = require("./policies");
+const cache_1 = require("./cache");
 const http_2 = require("./http");
 const pagination_2 = require("./pagination");
 const helpers_1 = require("./helpers");
@@ -182,6 +189,13 @@ class ForumulateClient {
     content = this.ns('content', (0, content_1.contentApi)((method, path, opts) => this.http(method, path, opts)));
     /** Translations of every kind of piece, routed by space type — see ./translations. */
     translations = (0, translations_1.translationsApi)((method, path, opts) => this.http(method, path, opts));
+    /** The policy acceptance gate: status, accept, claim, verify, the feed — see ./policies. */
+    policies = (0, policies_1.policiesApi)((method, path, opts = {}) => (0, http_2.send)(this.transport, { method, path, ...opts, version: this.apiVersion }), () => this.transport.baseUrl);
+    /** `cache.purge({ orgId, space, page })` over the generated `Cache_*` methods (FMU-B04). */
+    // Merged by hand rather than through `ns`: the hand-written half names every
+    // Cache_* operation itself, so the client type does not depend on the
+    // generated table having been refreshed first (the build runs before it).
+    cache = (0, resources_1.mergeNamespace)((0, resources_1.buildNamespace)('cache', this.invoke), (0, cache_1.cacheApi)((method, path) => this.http(method, path)));
     orgs = this.ns('orgs', this.helpers.orgs);
     spaces = this.ns('spaces', this.helpers.spaces);
     shapes = this.ns('shapes', this.helpers.shapes);