@everfur/sdk 0.1.1 → 0.4.0

package/dist/{identity-Brl-lDd6.d.cts → identity-C2-08BZW.d.cts}

@@ -1,12 +1,22 @@
-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';
+import { c as EverfurResult } from './EverfurResult-DN9pL2Ab.cjs';
+import { U as UserRef } from './ids-B2GAAifq.cjs';
+import { T as TransportPort, d as EverfurRequest } from './config--Wu1Umhd.cjs';
 
+/**
+ * A minted session token with the expiry the minter knows. `expiresAt` is what `mintPartnerSession` returns
+ * (epoch SECONDS), or epoch milliseconds, a Date or an ISO string; the SDK tells the units apart. Knowing it
+ * lets the runtime re-mint shortly before expiry, so no request pays a 401 round trip mid-session.
+ */
+interface MintedToken {
+    readonly token: string;
+    readonly expiresAt?: number | Date | string;
+}
 /**
  * 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.)
+ * A plain string is the original contract; a `MintedToken` additionally names the expiry.
  */
-type TokenProvider = () => Promise<string>;
+type TokenProvider = () => Promise<string | MintedToken>;
 interface IdentityProvider {
     readonly userRef: UserRef | null;
     /** Lazily mints on first call and caches in memory. forceRefresh drops the cache and re-mints. */
@@ -20,8 +30,11 @@ interface IdentityProvider {
 /**
  * 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.
+ * `onMinted` hears every successful mint with the expiry in epoch milliseconds (null when the minter named
+ * none); the runtime arms its proactive refresh from it. Scheduling lives there, not here, so this spine,
+ * which every capability closure carries, stays small.
  */
-declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider): IdentityProvider;
+declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider, onMinted?: (expiresAtMs: number | null) => void): IdentityProvider;
 type DeviceAuth = {
     readonly mode: 'personalized';
     readonly token: string;
@@ -42,7 +55,7 @@ type DeviceAuth = {
  * 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
+ * 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}$`
@@ -88,4 +101,4 @@ type AuthContext = {
  */
 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 };
+export { type AuthContext as A, type DeviceAuth as D, type IdentityProvider as I, type MintedToken as M, 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 → identity-CEi9GRFZ.d.ts}

@@ -1,12 +1,22 @@
-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';
+import { c as EverfurResult } from './EverfurResult-DN9pL2Ab.js';
+import { U as UserRef } from './ids-B2GAAifq.js';
+import { T as TransportPort, d as EverfurRequest } from './config-C7eb_IMD.js';
 
+/**
+ * A minted session token with the expiry the minter knows. `expiresAt` is what `mintPartnerSession` returns
+ * (epoch SECONDS), or epoch milliseconds, a Date or an ISO string; the SDK tells the units apart. Knowing it
+ * lets the runtime re-mint shortly before expiry, so no request pays a 401 round trip mid-session.
+ */
+interface MintedToken {
+    readonly token: string;
+    readonly expiresAt?: number | Date | string;
+}
 /**
  * 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.)
+ * A plain string is the original contract; a `MintedToken` additionally names the expiry.
  */
-type TokenProvider = () => Promise<string>;
+type TokenProvider = () => Promise<string | MintedToken>;
 interface IdentityProvider {
     readonly userRef: UserRef | null;
     /** Lazily mints on first call and caches in memory. forceRefresh drops the cache and re-mints. */
@@ -20,8 +30,11 @@ interface IdentityProvider {
 /**
  * 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.
+ * `onMinted` hears every successful mint with the expiry in epoch milliseconds (null when the minter named
+ * none); the runtime arms its proactive refresh from it. Scheduling lives there, not here, so this spine,
+ * which every capability closure carries, stays small.
  */
-declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider): IdentityProvider;
+declare function createIdentityProvider(userRef: UserRef, getToken: TokenProvider, onMinted?: (expiresAtMs: number | null) => void): IdentityProvider;
 type DeviceAuth = {
     readonly mode: 'personalized';
     readonly token: string;
@@ -42,7 +55,7 @@ type DeviceAuth = {
  * 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
+ * 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}$`
@@ -88,4 +101,4 @@ type AuthContext = {
  */
 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 };
+export { type AuthContext as A, type DeviceAuth as D, type IdentityProvider as I, type MintedToken as M, 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 → ids-B2GAAifq.d.cts}

@@ -43,4 +43,4 @@ 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 };
+export { type Brand as B, type ConversationId 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 ClientId as a, type ResponseId as b, conversationId as c, unsafeClientId as d, unsafeConversationId as e, unsafeDocumentId as f, unsafeJobId as g, unsafePetRef as h, unsafeRecordsRequestId as i, unsafeResponseId as j, unsafeUserRef as k, petRef as p, userRef as u };

package/dist/{ids-CJ1S6adf.d.ts → ids-B2GAAifq.d.ts}

@@ -43,4 +43,4 @@ 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 };
+export { type Brand as B, type ConversationId 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 ClientId as a, type ResponseId as b, conversationId as c, unsafeClientId as d, unsafeConversationId as e, unsafeDocumentId as f, unsafeJobId as g, unsafePetRef as h, unsafeRecordsRequestId as i, unsafeResponseId as j, unsafeUserRef as k, petRef as p, userRef as u };