@everfur/sdk 0.1.1 → 0.3.0

package/dist/copy-bKDNigLb.d.cts

@@ -0,0 +1,198 @@
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.cjs';
+import { R as RequestFunnel } from './requestFunnel-L-BQfi0z.cjs';
+import { A as AuthContext } from './identity-DI4eVx9S.cjs';
+import { U as UserRef } from './ids-B2GAAifq.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+
+/**
+ * The consent scopes a member controls from an embedded surface: exactly the scopes a backend gate reads off
+ * this ledger. Declaration order is the order a surface lists them in.
+ */
+declare const EVERFUR_CONSENT_SCOPES: readonly ["transcript_exposure", "partner_context"];
+/** One scope of the consent ledger. */
+type EverfurConsentScope = (typeof EVERFUR_CONSENT_SCOPES)[number];
+/** `consent_version: Field(None, max_length=64)` on the PUT body. */
+declare const CONSENT_VERSION_MAX = 64;
+/** True for a scope this SDK surfaces. `records_content` is deliberately NOT one; see the module header. */
+declare function isEverfurConsentScope(value: unknown): value is EverfurConsentScope;
+/**
+ * The resolved consent state for one scope, fail-closed.
+ *
+ * `granted` and `hasDecision` are not the same question, and a surface that conflates them is a dark
+ * pattern. `hasDecision: false` means nobody has asked yet, which is the state that should raise the
+ * prompt. `granted: false` with `hasDecision: true` means the member said no, and asking again is nagging.
+ */
+interface EverfurConsentVerdict {
+    readonly scope: EverfurConsentScope;
+    readonly granted: boolean;
+    readonly hasDecision: boolean;
+    /** The policy version in force when the decision was recorded, or null when there is none. */
+    readonly consentVersion: string | null;
+    /** Who authored the decision, as the server recorded it (`end_user` or `system`), or null. */
+    readonly actor: string | null;
+    /** ISO 8601, or null when there is no decision on record. */
+    readonly recordedAt: string | null;
+}
+/** One decision to append: the scope, whether it is a grant or a withdrawal, and the version shown. */
+interface EverfurConsentDecision {
+    readonly scope: EverfurConsentScope;
+    /** `true` to grant, `false` to withdraw. A withdrawal is the same route, never a harder path. */
+    readonly granted: boolean;
+    /** The version of the consent text the member was shown; the server defaults it when omitted. */
+    readonly consentVersion?: string;
+}
+interface ConsentRepository {
+    /**
+     * `GET /widget/v1/consent?scope=...` - the current verdict for the signed-in member. Settles
+     * `ok(EverfurConsentVerdict)` on 200 and `err(EverfurError)` otherwise. Never throws.
+     */
+    read(scope: EverfurConsentScope, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<EverfurResult<EverfurConsentVerdict>>;
+    /**
+     * `PUT /widget/v1/consent` - append a grant or a withdrawal. The actor is fixed server-side to the
+     * authenticated member, so nothing here sends one. Settles `ok(EverfurConsentVerdict)`; never throws.
+     */
+    write(decision: EverfurConsentDecision, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<EverfurResult<EverfurConsentVerdict>>;
+}
+/**
+ * The part of the runtime this repository needs: the current auth at call time, the partner's error policy,
+ * and whether the runtime is gone. `useEverfurContext().runtime` satisfies it; the narrow shape keeps this
+ * subpath's public types down to what it reads.
+ */
+interface ConsentRuntime {
+    readonly isDisposed: boolean;
+    readonly registry: {
+        readonly services: {
+            authFor(userRef: UserRef | null): AuthContext;
+            readonly errorPolicy: ErrorPolicyPort | undefined;
+        };
+    };
+}
+/** The lower seam: the repository over one already-built auth context, or an already-built funnel (tests). */
+interface ConsentRepositoryDeps {
+    readonly auth: AuthContext;
+    readonly errorPolicy?: ErrorPolicyPort;
+    /** Internal test seam: an already-built funnel. */
+    readonly funnel?: RequestFunnel;
+}
+/**
+ * The repository over the runtime under your provider (`useEverfurContext().runtime`). Auth is read at CALL
+ * time, so one repository serves every sign-in, and a disposed runtime settles every verb without a request.
+ */
+declare function createConsentRepository(runtime: ConsentRuntime): ConsentRepository;
+/** The same repository over one auth context (or an injected funnel). Internal seam, for deterministic tests. */
+declare function createConsentRepositoryOver(deps: ConsentRepositoryDeps): ConsentRepository;
+
+/** `signed_out`: no member on the provider. `failed`: every scope's read was refused; `refresh()` retries. */
+type EverfurConsentStatus = 'signed_out' | 'loading' | 'ready' | 'failed';
+/** One scope's state, as a surface renders it. */
+interface EverfurConsentScopeState {
+    readonly scope: EverfurConsentScope;
+    /** The member's current answer. Fail-closed: false until the server says otherwise. */
+    readonly granted: boolean;
+    /**
+     * Whether anyone has asked yet. `false` is the PROMPT state; `granted: false` with `hasDecision: true` is a
+     * refusal on record, and asking again is nagging.
+     */
+    readonly hasDecision: boolean;
+    /** The policy version in force when the decision was recorded, or null. */
+    readonly consentVersion: string | null;
+    /** ISO 8601, or null when there is no decision on record. */
+    readonly recordedAt: string | null;
+    /**
+     * Whether the verdict above came back from the server. False means this scope has NO answer on record
+     * here: either its read has not settled or its read was refused (`error` says which). It is not the same
+     * question as `hasDecision`, which is about the member; this one is about us.
+     */
+    readonly loaded: boolean;
+    /** True while THIS scope's write is in flight. The other scopes stay usable. */
+    readonly saving: boolean;
+    /** This scope's last read or write failure, or null. `error.displayMessage` is safe to show. */
+    readonly error: EverfurError | null;
+}
+/** What the hook reads. Omit it and every scope this SDK surfaces is read. */
+interface EverfurConsentOptions {
+    /**
+     * Read only these scopes. A toggle that renders ONE act passes its own scope, so mounting two toggles is two
+     * reads rather than four. An unknown value is dropped; an empty result falls back to every scope.
+     */
+    readonly scopes?: readonly EverfurConsentScope[];
+}
+interface EverfurConsentState {
+    readonly status: EverfurConsentStatus;
+    /** One entry per scope, in `EVERFUR_CONSENT_SCOPES` order. Empty only before the first read settles. */
+    readonly scopes: readonly EverfurConsentScopeState[];
+    /** The failure that made the whole read fail, or null. Per-scope failures hang off the scope. */
+    readonly error: EverfurError | null;
+    /**
+     * Grant or withdraw one scope. Optimistic: the switch flips now and rolls back if the wire refuses.
+     * Settles an `EverfurResult`; never throws.
+     */
+    setConsent(scope: EverfurConsentScope, granted: boolean): Promise<EverfurResult<EverfurConsentVerdict>>;
+    /** Read every scope again (the way out of `failed`, and the way to pick up a decision made elsewhere). */
+    refresh(): Promise<void>;
+}
+/**
+ * The consent repository bound to the runtime under your provider, for imperative callers (a settings screen
+ * that reads one scope without mounting the hook). Auth is read at call time, so one repository serves every
+ * sign-in.
+ */
+declare function useEverfurConsentRepository(): ConsentRepository;
+/**
+ * Read the member's consent state for every scope this SDK surfaces, and let them change it. Mount it on the
+ * screen where a member manages their data; `EverfurConsentToggle` renders one scope of it on either host.
+ */
+declare function useEverfurConsent(options?: EverfurConsentOptions): EverfurConsentState;
+
+/** What a band paints. `row` is the only state carrying a switch; every other state carries none. */
+type ConsentRowView = 
+/** No member on the provider: a switch here could not write, so none is offered. */
+{
+    readonly kind: 'signedOut';
+}
+/** The read has not settled yet. */
+ | {
+    readonly kind: 'loading';
+}
+/** This scope could not be READ, so there is no answer to show. `error.displayMessage` is the safe copy. */
+ | {
+    readonly kind: 'failed';
+    readonly error: EverfurError;
+} | {
+    readonly kind: 'row';
+    readonly scope: EverfurConsentScope;
+    readonly granted: boolean;
+    /** false is the never-asked state: the switch is off and nothing claims the member answered. */
+    readonly hasDecision: boolean;
+    /** This scope's write is in flight: the switch shows the optimistic answer and takes no new tap. */
+    readonly saving: boolean;
+    /** The last WRITE's refusal, after the switch was rolled back, or null. The switch stays usable. */
+    readonly error: EverfurError | null;
+};
+/**
+ * The view for one scope of a consent state.
+ *
+ * A scope the state does not carry yet is `loading`, never an empty row: inventing an ungranted row for it
+ * would paint a consent answer nobody gave.
+ */
+declare function consentRowView(state: EverfurConsentState, scope: EverfurConsentScope): ConsentRowView;
+
+/** One scope's row copy. `body` takes the partner's display name, the referent the member recognises. */
+interface ConsentScopeCopy {
+    readonly title: string;
+    readonly body: (partner: string) => string;
+}
+declare const CONSENT_COPY: Readonly<{
+    loading: "Loading";
+    retry: "Try again";
+    signedOut: "Sign in required";
+    changeable: "You can change this at any time.";
+    saving: "Saving";
+}>;
+/** AUTHORED (2026-09-20), pending copy review. One entry per scope this SDK surfaces. */
+declare const CONSENT_SCOPE_COPY: Readonly<Record<EverfurConsentScope, ConsentScopeCopy>>;
+
+export { CONSENT_COPY as C, type EverfurConsentScope as E, CONSENT_SCOPE_COPY as a, CONSENT_VERSION_MAX as b, type ConsentRepository as c, type ConsentRepositoryDeps as d, type ConsentRowView as e, type ConsentRuntime as f, type ConsentScopeCopy as g, EVERFUR_CONSENT_SCOPES as h, type EverfurConsentDecision as i, type EverfurConsentOptions as j, type EverfurConsentScopeState as k, type EverfurConsentState as l, type EverfurConsentStatus as m, type EverfurConsentVerdict as n, consentRowView as o, createConsentRepository as p, createConsentRepositoryOver as q, isEverfurConsentScope as r, useEverfurConsentRepository as s, useEverfurConsent as u };