@forumulate/sdk 0.7.0 → 0.10.0

package/dist/policies.d.ts

@@ -0,0 +1,264 @@
+/**
+ * The policy acceptance gate, from your server: `client.policies`.
+ *
+ *   status      what this user still has to accept before this event
+ *   accept      record an acceptance your own UI collected (server-verified)
+ *   claim       redeem a sign-up receipt for the account you just created
+ *   ticket      mint a ticket online (when your server holds a PAT, not the gate key)
+ *   verify      check an acceptance token online (offline: `verifyAcceptanceToken`)
+ *   acceptances the acceptance log; `export` as CSV or JSON
+ *   erase       a data-subject request: delete one person's acceptances
+ *   list        the policies themselves, from the policy feed (signed or public)
+ *   release     one exact published version, for ever
+ *
+ * Hand-written over the transport, like `./translations`, because the
+ * generated `schema.ts` is refreshed from the DEPLOYED spec and these routes
+ * ship with this release. The shapes are the contract in
+ * `packages/shared/src/policy-gate/dtos.ts`, restated: the SDK has no runtime
+ * dependencies, so it cannot import them.
+ */
+import type { PolicyFeedList } from './policy-feed';
+import type { PolicyGateEvent } from './policy-tokens';
+type Send = <T>(method: string, path: string, opts?: {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    kind?: 'json' | 'text';
+    maxRetries?: number;
+}) => Promise<T>;
+export type PolicyPresentation = 'checkbox' | 'checkbox-modal' | 'modal' | 'inline-scroll' | 'page' | 'link';
+export type PolicyGateReason = 'sign_up' | 'never_accepted' | 'new_version' | 'grace_period' | 'grace_expired' | 'accepted' | 'reaccept_never' | 'not_for_event' | 'not_yet_effective';
+/** One policy's verdict for a subject and event. */
+export interface PolicyGateStatusItem {
+    key: string;
+    title: string;
+    /** Show it now. */
+    ask: boolean;
+    /** Withhold the event until it is accepted. */
+    blocking: boolean;
+    reason: PolicyGateReason;
+    required: boolean;
+    version: string | null;
+    effectiveAt: string | null;
+    contentUrl: string | null;
+    /** SHA-256 (hex) of `contentHtml`: send it back when recording the acceptance. */
+    contentSha256: string | null;
+    /** With `includeContent: true`. */
+    contentHtml?: string | null;
+    summaryOfChanges: string | null;
+    acceptedVersion: string | null;
+    /** When a grace period ends. */
+    dueAt: string | null;
+    /** A future version that can be accepted early. */
+    upcoming: {
+        version: string;
+        effectiveAt: string;
+    } | null;
+    presentation: PolicyPresentation;
+    requireScroll: boolean;
+    showSummary: boolean;
+    decline: 'allow' | 'block';
+    dismissible: boolean;
+    reaccept: 'never' | 'next_sign_in' | 'grace_days';
+    events: PolicyGateEvent[];
+    /** Which level decided each behaviour field: `call`, `space`, `org`, `policy` or `default`. */
+    sources: Record<string, string>;
+}
+export interface PolicyGateStatus {
+    enabled: boolean;
+    subject: string | null;
+    event: PolicyGateEvent;
+    /** Nothing blocks the event. */
+    satisfied: boolean;
+    /** Keys still blocking. */
+    pending: string[];
+    /** Keys asked but not required. */
+    optional: string[];
+    policies: PolicyGateStatusItem[];
+    /** The database clock the rules were evaluated at. */
+    evaluatedAt: string;
+}
+/** One policy being accepted: which version, the hash of what was shown, and how. */
+export interface PolicyAcceptanceItem {
+    key: string;
+    version: string;
+    contentSha256: string;
+    presentation: PolicyPresentation;
+    scrolledToEnd?: boolean;
+}
+export interface PolicyAcceptanceRow {
+    id: string;
+    spaceId: string;
+    subject: string;
+    subjectEmailHash: string | null;
+    key: string;
+    version: string;
+    contentSha256: string;
+    presentation: PolicyPresentation;
+    display: 'checkbox' | 'scroll' | 'link';
+    scrolledToEnd: boolean;
+    event: PolicyGateEvent | null;
+    /** `server`, `ticket`, `receipt` or `unverified`. */
+    verification: string;
+    sourceApp: string | null;
+    locale: string | null;
+    ip: string | null;
+    userAgent: string | null;
+    batchId: string;
+    acceptedAt: string;
+}
+export interface PolicyAcceptanceResult {
+    acceptances: PolicyAcceptanceRow[];
+    /** A signed acceptance token for the subject. */
+    token: string;
+    expiresAt: string;
+    satisfied: boolean;
+    pending: string[];
+}
+/** Email, or its hash: who the subject is, for a later data-subject request. */
+export interface PolicySubjectIdentity {
+    /** Hashed on arrival, never stored. */
+    email?: string;
+    /** SHA-256 hex of the trimmed, lower-cased email (`policyEmailHash`). */
+    emailHash?: string;
+}
+export interface PolicyGateSpace {
+    orgId: string;
+    /** The Legal space whose published policies gate your app. */
+    spaceId: string;
+}
+export interface PolicyStatusInput extends PolicyGateSpace {
+    /** Your id for the user. Omit on a sign-up: everything is asked. */
+    subject?: string;
+    event: PolicyGateEvent;
+    /** Include each version's `contentHtml` (to show it in your own UI). */
+    includeContent?: boolean;
+}
+export interface PolicyAcceptInput extends PolicyGateSpace, PolicySubjectIdentity {
+    subject: string;
+    event?: PolicyGateEvent;
+    policies: PolicyAcceptanceItem[];
+    /** Recorded as `sourceApp` (`web`, `ios`). */
+    sourceApp?: string;
+    /** The END USER's IP, which your server saw and Forumulate did not. */
+    ip?: string;
+    /** The END USER's user agent. */
+    userAgent?: string;
+    locale?: string;
+}
+export interface PolicyListInput {
+    /** The Legal space. */
+    spaceId: string;
+    /** One policy only. */
+    key?: string;
+    /**
+     * The link's shared secret (`whsec_…`) from **Policy sources**: reads the
+     * signed feed. Without it, the public feed is read (404 unless the space
+     * turned it on).
+     */
+    secret?: string;
+    /** Sign with `atlas-*` headers at the Atlas address instead. */
+    prefix?: 'forumulate' | 'atlas';
+}
+/**
+ * The acceptance items for every policy a status asks for — what to send to
+ * `accept` once your own UI has shown them. `presentation` is how YOU showed
+ * them; it is recorded as such.
+ */
+export declare function acceptanceItemsFrom(status: Pick<PolicyGateStatus, 'policies'>, shown: {
+    presentation: PolicyPresentation;
+    scrolledToEnd?: boolean;
+    keys?: string[];
+}): PolicyAcceptanceItem[];
+export declare function policiesApi(send: Send, baseUrl: () => string): {
+    /** What `subject` still has to accept before `event`. `satisfied` false = withhold the event. */
+    status: (input: PolicyStatusInput) => Promise<PolicyGateStatus>;
+    /** Record what your own UI collected. Answers with a signed acceptance token. */
+    accept: (input: PolicyAcceptInput) => Promise<PolicyAcceptanceResult>;
+    /** Redeem a sign-up receipt for the account you just created. Once only. */
+    claim: (input: PolicyGateSpace & PolicySubjectIdentity & {
+        receipt: string;
+        subject: string;
+    }) => Promise<PolicyAcceptanceResult>;
+    /**
+     * Mint a ticket online. Signing it yourself with `signPolicyTicket` needs
+     * no call; this is for a server that holds a PAT but not the gate key.
+     */
+    ticket: (input: PolicyGateSpace & PolicySubjectIdentity & {
+        subject: string;
+        event: PolicyGateEvent;
+        sourceApp?: string;
+        returnUrl?: string;
+        state?: string;
+        locale?: string;
+        ttlSeconds?: number;
+    }) => Promise<{
+        ticket: string;
+        expiresAt: string;
+        pageUrl: string;
+    }>;
+    /** Verify a token online. Offline (no round trip): `verifyAcceptanceToken`. */
+    verify: (input: PolicyGateSpace & {
+        token: string;
+        subject?: string;
+    }) => Promise<{
+        valid: boolean;
+        reason?: string;
+        claims?: Record<string, unknown>;
+    }>;
+    /** The acceptance log, newest first; pass `page.nextCursor` back as `cursor`. */
+    acceptances: (input: PolicyGateSpace & PolicySubjectIdentity & {
+        subject?: string;
+        key?: string;
+        cursor?: string;
+        limit?: number;
+    }) => Promise<{
+        acceptances: PolicyAcceptanceRow[];
+        page: {
+            limit: number;
+            hasMore: boolean;
+            nextCursor: string | null;
+        };
+    }>;
+    /** The log as a file (CSV or JSON text). */
+    export: (input: PolicyGateSpace & {
+        format: "csv" | "json";
+        subject?: string;
+        emailHash?: string;
+        key?: string;
+    }) => Promise<string>;
+    /** A data-subject erasure: every acceptance of one person, across the org's spaces. */
+    erase: (input: {
+        orgId: string;
+    } & PolicySubjectIdentity & {
+        subject?: string;
+    }) => Promise<{
+        erased: number;
+    }>;
+    /**
+     * The policies, from Forumulate policy feed v1. With `secret`, the signed
+     * feed (`/policy-feed/spaces/{id}/policies`, or Atlas's address with
+     * `prefix: 'atlas'`); without, the public one.
+     */
+    list: (input: PolicyListInput) => Promise<PolicyFeedList>;
+    /** One exact published version — the text behind its `content_url`, which never changes. */
+    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;
+        };
+    }>;
+};
+export type PoliciesApi = ReturnType<typeof policiesApi>;
+export {};
+//# sourceMappingURL=policies.d.ts.map

package/dist/policies.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acceptanceItemsFrom = acceptanceItemsFrom;
+exports.policiesApi = policiesApi;
+const policy_feed_1 = require("./policy-feed");
+/**
+ * The acceptance items for every policy a status asks for — what to send to
+ * `accept` once your own UI has shown them. `presentation` is how YOU showed
+ * them; it is recorded as such.
+ */
+function acceptanceItemsFrom(status, shown) {
+    return status.policies
+        .filter((p) => p.ask && p.version && p.contentSha256)
+        .filter((p) => !shown.keys || shown.keys.includes(p.key))
+        .map((p) => ({
+        key: p.key,
+        version: p.version,
+        contentSha256: p.contentSha256,
+        presentation: shown.presentation,
+        ...(shown.scrolledToEnd === undefined ? {} : { scrolledToEnd: shown.scrolledToEnd }),
+    }));
+}
+const e = encodeURIComponent;
+function policiesApi(send, baseUrl) {
+    const gate = (s) => `/orgs/${e(s.orgId)}/spaces/${e(s.spaceId)}/policy-gate`;
+    const strip = (input) => {
+        const { orgId: _o, spaceId: _s, ...rest } = input;
+        return rest;
+    };
+    return {
+        /** What `subject` still has to accept before `event`. `satisfied` false = withhold the event. */
+        status: (input) => send('GET', `${gate(input)}/status`, {
+            query: {
+                subject: input.subject,
+                event: input.event,
+                include: input.includeContent ? 'content' : undefined,
+            },
+        }),
+        /** Record what your own UI collected. Answers with a signed acceptance token. */
+        accept: (input) => send('POST', `${gate(input)}/acceptances`, { body: strip(input) }),
+        /** Redeem a sign-up receipt for the account you just created. Once only. */
+        claim: (input) => send('POST', `${gate(input)}/acceptances/claim`, { body: strip(input) }),
+        /**
+         * Mint a ticket online. Signing it yourself with `signPolicyTicket` needs
+         * no call; this is for a server that holds a PAT but not the gate key.
+         */
+        ticket: (input) => send('POST', `${gate(input)}/tickets`, {
+            body: strip(input),
+        }),
+        /** Verify a token online. Offline (no round trip): `verifyAcceptanceToken`. */
+        verify: (input) => send('POST', `${gate(input)}/tokens/verify`, { body: strip(input) }),
+        /** The acceptance log, newest first; pass `page.nextCursor` back as `cursor`. */
+        acceptances: (input) => send('GET', `${gate(input)}/acceptances`, { query: strip(input) }),
+        /** The log as a file (CSV or JSON text). */
+        export: (input) => send('GET', `${gate(input)}/acceptances/export`, {
+            query: strip(input),
+            kind: 'text',
+        }),
+        /** A data-subject erasure: every acceptance of one person, across the org's spaces. */
+        erase: (input) => {
+            const { orgId, ...body } = input;
+            return send('POST', `/orgs/${e(orgId)}/policy-gate/subjects/erase`, { body });
+        },
+        /**
+         * The policies, from Forumulate policy feed v1. With `secret`, the signed
+         * feed (`/policy-feed/spaces/{id}/policies`, or Atlas's address with
+         * `prefix: 'atlas'`); without, the public one.
+         */
+        list: async (input) => {
+            const q = input.key ? `?key=${e(input.key)}` : '';
+            if (!input.secret) {
+                return send('GET', `/public/spaces/${e(input.spaceId)}/policies${q}`);
+            }
+            const route = input.prefix === 'atlas'
+                ? `/atlas/spaces/${e(input.spaceId)}/policies${q}`
+                : `/policy-feed/spaces/${e(input.spaceId)}/policies${q}`;
+            // The signature covers the path AS REQUESTED, so the base URL's own path
+            // (`/api` on forumulate.com) is part of it.
+            const prefix = new URL(baseUrl()).pathname.replace(/\/+$/, '');
+            const headers = await (0, policy_feed_1.signPolicyFeedRequest)({
+                secret: input.secret,
+                path: `${prefix}${route}`,
+                prefix: input.prefix,
+            });
+            // No retries: the request id is single-use, so a retry of a request that
+            // reached the server is refused as a replay. Call again to re-sign.
+            return send('GET', route, { headers, maxRetries: 0 });
+        },
+        /** One exact published version — the text behind its `content_url`, which never changes. */
+        release: (input) => send('GET', `/public/orgs/${e(input.orgId)}/legal/${e(input.key)}/releases/${e(input.version)}`),
+    };
+}
+//# sourceMappingURL=policies.js.map

package/dist/policy-crypto.d.ts

@@ -0,0 +1,5 @@
+/** Byte helpers the policy files share. Internal: not re-exported from the package. */
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(s: string): Uint8Array;
+export declare function equalBytes(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=policy-crypto.d.ts.map

package/dist/policy-crypto.js

@@ -0,0 +1,31 @@
+"use strict";
+/** Byte helpers the policy files share. Internal: not re-exported from the package. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64UrlEncode = base64UrlEncode;
+exports.base64UrlDecode = base64UrlDecode;
+exports.equalBytes = equalBytes;
+function base64UrlEncode(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlDecode(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new TypeError('not base64url');
+    const pad = s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (s.length % 4)) % 4);
+    const bin = atob(pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+//# sourceMappingURL=policy-crypto.js.map

package/dist/policy-feed.d.ts

@@ -0,0 +1,139 @@
+/** One version in the feed. Field names are the protocol's (snake_case). */
+export interface PolicyFeedVersion {
+    version: string;
+    published_at: string;
+    effective_at: string;
+    content_html?: string;
+    content_markdown?: string;
+    /** Public URL of exactly this version; it never changes. */
+    content_url: string;
+    /** SHA-256 hex of `content_html`, so a consumer can check what it stored. */
+    content_sha256?: string;
+    summary_of_changes?: string;
+    locale?: string;
+}
+export interface PolicyFeedPolicy {
+    key: string;
+    title: string;
+    display: 'checkbox' | 'scroll' | 'link';
+    required: boolean;
+    applies_to: 'sign_up' | 'sign_in_and_sign_up';
+    /** `never`, `next_sign_in` or `grace_days:N`. */
+    reaccept?: string;
+    versions: PolicyFeedVersion[];
+}
+export interface PolicyFeedList {
+    object: 'policy_list';
+    policies: PolicyFeedPolicy[];
+}
+export type PolicyWebhookEvent = {
+    type: 'policy.published';
+    key: string;
+    version: string;
+    occurred_at: string;
+} | {
+    type: 'policy.retired';
+    key: string;
+    occurred_at: string;
+};
+/** The HMAC key a secret stands for: the decoded bytes of a `whsec_` secret, else its UTF-8. */
+export declare function policySecretKey(secret: string): Uint8Array;
+/** Headers as a Fetch `Headers`, a Node `IncomingHttpHeaders` or a plain record. */
+export type HeaderBag = Headers | Record<string, string | string[] | undefined | null> | {
+    get(name: string): string | null;
+};
+/** The exact string a feed request signs. */
+export declare function policyFeedSigningString(id: string, timestamp: string, path: string): string;
+export interface SignPolicyFeedRequestInput {
+    /** The link's shared secret (`whsec_…`). During a rotation, pass both: every one signs. */
+    secret: string | readonly string[];
+    /** Path plus query as you will request it, e.g. `/api/policy-feed/spaces/sp_1/policies?key=tos`. */
+    path: string;
+    /** Unique per request; the source refuses a repeat within five minutes. Default: random. */
+    id?: string;
+    /** Unix milliseconds. Default: now. */
+    timestamp?: number;
+    /** `forumulate` (default) or `atlas`, for the header names. */
+    prefix?: 'forumulate' | 'atlas';
+}
+/**
+ * The three headers that sign one feed request. Use a fresh call per request:
+ * the id is single-use, so a retry must be signed again.
+ *
+ * ```ts
+ * const path = `/api/policy-feed/spaces/${spaceId}/policies`;
+ * const headers = await signPolicyFeedRequest({ secret: process.env.POLICY_FEED_SECRET!, path });
+ * const list = await (await fetch(`https://forumulate.com${path}`, { headers })).json();
+ * ```
+ */
+export declare function signPolicyFeedRequest(input: SignPolicyFeedRequestInput): Promise<Record<string, string>>;
+export type PolicyFeedRequestFailure = 'missing_headers' | 'stale_timestamp' | 'bad_signature' | 'replayed';
+export interface VerifyPolicyFeedRequestInput {
+    /** Every secret still valid for the link: the current one and, for 24 h after a rotation, the previous. */
+    secrets: string | readonly string[];
+    headers: HeaderBag;
+    /**
+     * The path plus query the CONSUMER requested. Pass several when a proxy in
+     * front of you rewrites it (`/api/…` outside, `/…` inside): any one matching
+     * is enough.
+     */
+    path: string | readonly string[];
+    /** Milliseconds of clock difference allowed. Default 300 000 (five minutes). */
+    toleranceMs?: number;
+    /**
+     * Replay protection: return `true` if this id was already seen in the last
+     * five minutes (and remember it). Without it, a captured request can be
+     * replayed inside the window — fine for a read-only feed, but say so.
+     */
+    seen?: (id: string) => boolean | Promise<boolean>;
+    /** Unix milliseconds; defaults to now. */
+    now?: number;
+}
+/**
+ * Check a signed feed request — the half a policy SOURCE implements. Either
+ * header spelling (`forumulate-*` or `atlas-*`) is read.
+ */
+export declare function verifyPolicyFeedRequest(input: VerifyPolicyFeedRequestInput): Promise<{
+    valid: true;
+    id: string;
+} | {
+    valid: false;
+    reason: PolicyFeedRequestFailure;
+}>;
+export declare class PolicyWebhookError extends Error {
+    readonly reason: 'missing_headers' | 'stale_timestamp' | 'bad_signature' | 'bad_body';
+    constructor(reason: 'missing_headers' | 'stale_timestamp' | 'bad_signature' | 'bad_body', message: string);
+}
+export interface VerifyPolicyWebhookOptions {
+    /** Seconds a delivery may be old (or early). Default 300; 0 skips the check. */
+    toleranceSeconds?: number;
+    /** Unix milliseconds; defaults to now. */
+    now?: number;
+}
+/**
+ * Verify a `policy.published` / `policy.retired` notice and parse it. Throws
+ * {@link PolicyWebhookError} — the parse can never run ahead of the check.
+ *
+ * `body` must be the RAW request body: a re-serialised object has different
+ * bytes and never verifies. During a secret rotation pass both secrets.
+ * Dedupe on `webhook-id`: a retry of one event reuses it.
+ *
+ * ```ts
+ * const event = await verifyPolicyWebhook(req.headers, rawBody, process.env.POLICY_FEED_SECRET!);
+ * if (event.type === 'policy.published') await refreshPolicies(event.key);
+ * ```
+ */
+export declare function verifyPolicyWebhook(headers: HeaderBag, body: string | Uint8Array, secret: string | readonly string[], opts?: VerifyPolicyWebhookOptions): Promise<PolicyWebhookEvent>;
+/** Standard Webhooks headers for one notice — the SENDING half, for a platform implementing the protocol. */
+export declare function signPolicyWebhook(input: {
+    secret: string | readonly string[];
+    body: string;
+    id?: string;
+    /** Unix seconds. Default: now. */
+    timestamp?: number;
+}): Promise<{
+    'webhook-id': string;
+    'webhook-timestamp': string;
+    'webhook-signature': string;
+}>;
+//# sourceMappingURL=policy-feed.d.ts.map