@everfur/sdk 0.1.0

package/dist/identity-Brl-lDd6.d.cts

@@ -0,0 +1,91 @@
+import { E as EverfurResult } from './EverfurResult-D92-uL82.cjs';
+import { U as UserRef } from './ids-CJ1S6adf.cjs';
+import { T as TransportPort, E as EverfurRequest } from './config-BSjBdxrZ.cjs';
+
+/**
+ * Supplies a session token. The partner-backend implementation hits POST /widget/v1/sessions and returns the
+ * session_token; it always mints fresh. The SDK caches the result in IdentityProvider memory. (SPEC-00 4.3.)
+ */
+type TokenProvider = () => Promise<string>;
+interface IdentityProvider {
+    readonly userRef: UserRef | null;
+    /** Lazily mints on first call and caches in memory. forceRefresh drops the cache and re-mints. */
+    currentToken(opts?: {
+        readonly forceRefresh?: boolean;
+    }): Promise<string>;
+    hasToken(): boolean;
+    /** Drop the cached bearer (user switch / logout) so a stale token is never sent post-switch. */
+    clear(): void;
+}
+/**
+ * Memory-only identity. The token is NEVER written through KvPort or to disk (SPEC-00 4.3, identity.dart
+ * 12,47-57). Concurrent callers share one in-flight mint so a burst of authed requests mints exactly once.
+ */
+declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider): IdentityProvider;
+type DeviceAuth = {
+    readonly mode: 'personalized';
+    readonly token: string;
+    readonly userRef: UserRef | null;
+    readonly sessionId?: string;
+} | {
+    readonly mode: 'anonymous';
+    readonly publishableKey: string;
+    readonly userRef: UserRef | null;
+    readonly sessionId?: string;
+};
+/**
+ * A v4 UUID for `x-everfur-session-id`, minted ONCE per runtime.
+ *
+ * WHY THIS EXISTS, and why the header is not optional in practice. The server's own helper documents the
+ * header as "optional ... solely for analytics correlation", and when it is absent or not a strict v4 it
+ * substitutes `str(uuid.uuid4())` PER REQUEST. For a personalized caller that is harmless. For an ANONYMOUS
+ * caller it is not: the widget context derives the identity from it (`user_ref = f"anon-{session_id}"`), so
+ * without a stable value every request is a different user. `POST /conversations` creates the thread under
+ * one identity and the very next `POST /conversations/{id}/messages` is resolved as another, the ownership
+ * check misses, and the send settles `conversationNotFound` — every time. Each attempt also inserts a junk
+ * virtual-user row and consumes the per-IP anonymous-creation budget.
+ *
+ * The format is load-bearing: the server matches `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
+ * and SILENTLY replaces anything else, so a merely-random string would fail exactly as an absent one does.
+ */
+declare function newSessionId(): string;
+/**
+ * Build the auth headers for ONE device request. Personalized -> Authorization: Bearer alone. Anonymous ->
+ * x-everfur-partner-key alone. NEVER both (both on one device request trips a 403 edge deny). x-everfur-user-ref
+ * is attached when a user is set.
+ */
+declare function authHeaders(auth: DeviceAuth): Record<string, string>;
+/** Apply auth headers, stripping any partner-supplied auth header so the SDK is the sole authority. */
+declare function withAuthHeaders(req: EverfurRequest, auth: DeviceAuth): EverfurRequest;
+type AuthContext = {
+    readonly mode: 'personalized';
+    readonly transport: TransportPort;
+    readonly identity: IdentityProvider;
+    readonly userRef: UserRef | null;
+    /** Stable per runtime; see `newSessionId`. REQUIRED: an omission silently breaks anonymous identity. */
+    readonly sessionId: string;
+} | {
+    readonly mode: 'anonymous';
+    readonly transport: TransportPort;
+    readonly publishableKey: string;
+    readonly userRef: UserRef | null;
+    /**
+     * Stable per runtime; see `newSessionId`. REQUIRED, not optional.
+     *
+     * `AuthContext` is exported from the public `@everfur/sdk/client` subpath and three factories take one
+     * from the caller (`createPetsRepository`, `createHttpRecordsRepository`, `fetchEntitlements`). While
+     * this was optional, building a literal without it type-checked, compiled, and silently reintroduced
+     * the defect where every anonymous request resolves as a NEW server-side user. Making it required
+     * means `tsc` catches every omission instead.
+     */
+    readonly sessionId: string;
+};
+/**
+ * Send a unary request with device auth. Anonymous mode carries pk alone (no refresh path, no token).
+ * Personalized mode carries the bearer; on a 401 it re-mints once via TokenProvider(forceRefresh) and replays
+ * the original request EXACTLY once. A second 401, or a failed re-mint, surfaces terminal authRejected (not
+ * auto-retried). A 403 is distinct and is returned as-is (never a sign-out, never a refresh).
+ */
+declare function authedSend<T>(req: EverfurRequest, ctx: AuthContext): Promise<EverfurResult<T>>;
+
+export { type AuthContext as A, type DeviceAuth as D, type IdentityProvider as I, type TokenProvider as T, authHeaders as a, authedSend as b, createIdentityProvider as c, newSessionId as n, withAuthHeaders as w };

package/dist/identity-DK9zORrG.d.ts

@@ -0,0 +1,91 @@
+import { E as EverfurResult } from './EverfurResult-D92-uL82.js';
+import { U as UserRef } from './ids-CJ1S6adf.js';
+import { T as TransportPort, E as EverfurRequest } from './config-CiJ0PVBB.js';
+
+/**
+ * Supplies a session token. The partner-backend implementation hits POST /widget/v1/sessions and returns the
+ * session_token; it always mints fresh. The SDK caches the result in IdentityProvider memory. (SPEC-00 4.3.)
+ */
+type TokenProvider = () => Promise<string>;
+interface IdentityProvider {
+    readonly userRef: UserRef | null;
+    /** Lazily mints on first call and caches in memory. forceRefresh drops the cache and re-mints. */
+    currentToken(opts?: {
+        readonly forceRefresh?: boolean;
+    }): Promise<string>;
+    hasToken(): boolean;
+    /** Drop the cached bearer (user switch / logout) so a stale token is never sent post-switch. */
+    clear(): void;
+}
+/**
+ * Memory-only identity. The token is NEVER written through KvPort or to disk (SPEC-00 4.3, identity.dart
+ * 12,47-57). Concurrent callers share one in-flight mint so a burst of authed requests mints exactly once.
+ */
+declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider): IdentityProvider;
+type DeviceAuth = {
+    readonly mode: 'personalized';
+    readonly token: string;
+    readonly userRef: UserRef | null;
+    readonly sessionId?: string;
+} | {
+    readonly mode: 'anonymous';
+    readonly publishableKey: string;
+    readonly userRef: UserRef | null;
+    readonly sessionId?: string;
+};
+/**
+ * A v4 UUID for `x-everfur-session-id`, minted ONCE per runtime.
+ *
+ * WHY THIS EXISTS, and why the header is not optional in practice. The server's own helper documents the
+ * header as "optional ... solely for analytics correlation", and when it is absent or not a strict v4 it
+ * substitutes `str(uuid.uuid4())` PER REQUEST. For a personalized caller that is harmless. For an ANONYMOUS
+ * caller it is not: the widget context derives the identity from it (`user_ref = f"anon-{session_id}"`), so
+ * without a stable value every request is a different user. `POST /conversations` creates the thread under
+ * one identity and the very next `POST /conversations/{id}/messages` is resolved as another, the ownership
+ * check misses, and the send settles `conversationNotFound` — every time. Each attempt also inserts a junk
+ * virtual-user row and consumes the per-IP anonymous-creation budget.
+ *
+ * The format is load-bearing: the server matches `^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
+ * and SILENTLY replaces anything else, so a merely-random string would fail exactly as an absent one does.
+ */
+declare function newSessionId(): string;
+/**
+ * Build the auth headers for ONE device request. Personalized -> Authorization: Bearer alone. Anonymous ->
+ * x-everfur-partner-key alone. NEVER both (both on one device request trips a 403 edge deny). x-everfur-user-ref
+ * is attached when a user is set.
+ */
+declare function authHeaders(auth: DeviceAuth): Record<string, string>;
+/** Apply auth headers, stripping any partner-supplied auth header so the SDK is the sole authority. */
+declare function withAuthHeaders(req: EverfurRequest, auth: DeviceAuth): EverfurRequest;
+type AuthContext = {
+    readonly mode: 'personalized';
+    readonly transport: TransportPort;
+    readonly identity: IdentityProvider;
+    readonly userRef: UserRef | null;
+    /** Stable per runtime; see `newSessionId`. REQUIRED: an omission silently breaks anonymous identity. */
+    readonly sessionId: string;
+} | {
+    readonly mode: 'anonymous';
+    readonly transport: TransportPort;
+    readonly publishableKey: string;
+    readonly userRef: UserRef | null;
+    /**
+     * Stable per runtime; see `newSessionId`. REQUIRED, not optional.
+     *
+     * `AuthContext` is exported from the public `@everfur/sdk/client` subpath and three factories take one
+     * from the caller (`createPetsRepository`, `createHttpRecordsRepository`, `fetchEntitlements`). While
+     * this was optional, building a literal without it type-checked, compiled, and silently reintroduced
+     * the defect where every anonymous request resolves as a NEW server-side user. Making it required
+     * means `tsc` catches every omission instead.
+     */
+    readonly sessionId: string;
+};
+/**
+ * Send a unary request with device auth. Anonymous mode carries pk alone (no refresh path, no token).
+ * Personalized mode carries the bearer; on a 401 it re-mints once via TokenProvider(forceRefresh) and replays
+ * the original request EXACTLY once. A second 401, or a failed re-mint, surfaces terminal authRejected (not
+ * auto-retried). A 403 is distinct and is returned as-is (never a sign-out, never a refresh).
+ */
+declare function authedSend<T>(req: EverfurRequest, ctx: AuthContext): Promise<EverfurResult<T>>;
+
+export { type AuthContext as A, type DeviceAuth as D, type IdentityProvider as I, type TokenProvider as T, authHeaders as a, authedSend as b, createIdentityProvider as c, newSessionId as n, withAuthHeaders as w };

package/dist/ids-CJ1S6adf.d.cts

@@ -0,0 +1,46 @@
+/** Compile-time-only brand. Zero runtime cost; a raw string cannot flow into an id slot. */
+declare const __brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+type PetRef = Brand<string, 'PetRef'>;
+type UserRef = Brand<string, 'UserRef'>;
+type ConversationId = Brand<string, 'ConversationId'>;
+type ResponseId = Brand<string, 'ResponseId'>;
+type ClientId = Brand<string, 'ClientId'>;
+type DocumentId = Brand<string, 'DocumentId'>;
+type JobId = Brand<string, 'JobId'>;
+type RecordsRequestId = Brand<string, 'RecordsRequestId'>;
+/**
+ * Validating constructor for a partner-supplied pet id. Crosses the value at the adapter boundary.
+ * @throws {EverfurConfigError} synchronously on an empty, over-long, or non-printable id (programmer error).
+ */
+declare function petRef(raw: string): PetRef;
+/**
+ * Validating constructor for a partner-supplied end-user id (becomes x-everfur-user-ref).
+ * @throws {EverfurConfigError} synchronously on empty, over-long, containing '@', or non-printable.
+ */
+declare function userRef(raw: string): UserRef;
+/**
+ * Validating constructor for a server-owned conversation id.
+ * @throws {EverfurConfigError} synchronously if `raw` is not a UUID (programmer error).
+ */
+declare function conversationId(raw: string): ConversationId;
+/** Unchecked. For the response-mapper boundary where the value is already trusted. Adapters only. */
+declare function unsafePetRef(raw: string): PetRef;
+/** Unchecked. For the response-mapper boundary where the value is already trusted. Adapters only. */
+declare function unsafeUserRef(raw: string): UserRef;
+/** Unchecked. Server-owned; arrives pre-branded from a mapper. Adapters only. */
+declare function unsafeConversationId(raw: string): ConversationId;
+/** Unchecked. From the terminal `done`/completed frame. Adapters only. */
+declare function unsafeResponseId(raw: string): ResponseId;
+/** Unchecked. pk-resolved server-side. Adapters only. */
+declare function unsafeClientId(raw: string): ClientId;
+/** Unchecked. Server-owned medical-record doc id. Adapters only. */
+declare function unsafeDocumentId(raw: string): DocumentId;
+/** Unchecked. Server-owned async analysis-job id (video/photo). Adapters only. */
+declare function unsafeJobId(raw: string): JobId;
+/** Unchecked. Server-owned records-request handle (SPEC-11a). Adapters only. */
+declare function unsafeRecordsRequestId(raw: string): RecordsRequestId;
+
+export { type Brand as B, type ClientId as C, type DocumentId as D, type JobId as J, type PetRef as P, type RecordsRequestId as R, type UserRef as U, __brand as _, type ConversationId as a, type ResponseId as b, conversationId as c, unsafeConversationId as d, unsafeDocumentId as e, unsafeJobId as f, unsafePetRef as g, unsafeRecordsRequestId as h, unsafeResponseId as i, unsafeUserRef as j, userRef as k, petRef as p, unsafeClientId as u };

package/dist/ids-CJ1S6adf.d.ts

@@ -0,0 +1,46 @@
+/** Compile-time-only brand. Zero runtime cost; a raw string cannot flow into an id slot. */
+declare const __brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+type PetRef = Brand<string, 'PetRef'>;
+type UserRef = Brand<string, 'UserRef'>;
+type ConversationId = Brand<string, 'ConversationId'>;
+type ResponseId = Brand<string, 'ResponseId'>;
+type ClientId = Brand<string, 'ClientId'>;
+type DocumentId = Brand<string, 'DocumentId'>;
+type JobId = Brand<string, 'JobId'>;
+type RecordsRequestId = Brand<string, 'RecordsRequestId'>;
+/**
+ * Validating constructor for a partner-supplied pet id. Crosses the value at the adapter boundary.
+ * @throws {EverfurConfigError} synchronously on an empty, over-long, or non-printable id (programmer error).
+ */
+declare function petRef(raw: string): PetRef;
+/**
+ * Validating constructor for a partner-supplied end-user id (becomes x-everfur-user-ref).
+ * @throws {EverfurConfigError} synchronously on empty, over-long, containing '@', or non-printable.
+ */
+declare function userRef(raw: string): UserRef;
+/**
+ * Validating constructor for a server-owned conversation id.
+ * @throws {EverfurConfigError} synchronously if `raw` is not a UUID (programmer error).
+ */
+declare function conversationId(raw: string): ConversationId;
+/** Unchecked. For the response-mapper boundary where the value is already trusted. Adapters only. */
+declare function unsafePetRef(raw: string): PetRef;
+/** Unchecked. For the response-mapper boundary where the value is already trusted. Adapters only. */
+declare function unsafeUserRef(raw: string): UserRef;
+/** Unchecked. Server-owned; arrives pre-branded from a mapper. Adapters only. */
+declare function unsafeConversationId(raw: string): ConversationId;
+/** Unchecked. From the terminal `done`/completed frame. Adapters only. */
+declare function unsafeResponseId(raw: string): ResponseId;
+/** Unchecked. pk-resolved server-side. Adapters only. */
+declare function unsafeClientId(raw: string): ClientId;
+/** Unchecked. Server-owned medical-record doc id. Adapters only. */
+declare function unsafeDocumentId(raw: string): DocumentId;
+/** Unchecked. Server-owned async analysis-job id (video/photo). Adapters only. */
+declare function unsafeJobId(raw: string): JobId;
+/** Unchecked. Server-owned records-request handle (SPEC-11a). Adapters only. */
+declare function unsafeRecordsRequestId(raw: string): RecordsRequestId;
+
+export { type Brand as B, type ClientId as C, type DocumentId as D, type JobId as J, type PetRef as P, type RecordsRequestId as R, type UserRef as U, __brand as _, type ConversationId as a, type ResponseId as b, conversationId as c, unsafeConversationId as d, unsafeDocumentId as e, unsafeJobId as f, unsafePetRef as g, unsafeRecordsRequestId as h, unsafeResponseId as i, unsafeUserRef as j, userRef as k, petRef as p, unsafeClientId as u };