@everfur/sdk 0.1.0

package/dist/client/index.d.cts

@@ -0,0 +1,65 @@
+import { a as EverfurErrorCode } from '../EverfurResult-D92-uL82.cjs';
+export { A as AUTO_RETRYABLE_CODES, B as BACKOFF_BASE_MS, b as BACKOFF_CAP_MS, c as EVERFUR_ERROR_CATEGORIES, d as EVERFUR_ERROR_CODES, e as EverfurConfigError, f as EverfurError, g as EverfurErrorCategory, E as EverfurResult, h as EverfurThrownError, M as MAX_RETRY_ATTEMPTS, i as MakeEverfurErrorOptions, R as RETRYABLE_CONTRACT_CODES, j as backoffDelayMs, k as canRecreateOnNotFound, l as categoryFor, m as err, n as fromHttpStatus, o as fromWire, p as isAutoRetryable, q as isErr, r as isOk, s as isRetryableCode, t as makeEverfurError, u as ok, v as shouldRetry, w as unwrap, x as userFacingError } from '../EverfurResult-D92-uL82.cjs';
+export { A as AcceptedFrame, b as AnalysisCompleteFrame, c as AnalysisStartedFrame, B as ByteSource, C as ClientConfigFailure, d as ClientConfigFailureReason, e as ClientConfigOutcome, D as DEFAULT_CONTRACT_VERSION, f as DeltaFrame, g as DoneFrame, h as EMPTY_FRAME_ARRAYS, i as ENV_API_BASE_URL, j as ErrorFrame, k as EventSourceFactory, l as EventSourceInit, m as EventSourceLike, n as EventSourceMessage, o as EverfurConfig, E as EverfurRequest, p as EverfurRequestBase, q as FetchInit, a as FetchLike, r as FetchResponseLike, F as Frame, s as FrameBase, t as FrameKind, H as HeartbeatFrame, u as HttpMethod, M as MultipartBody, R as RawResponse, v as ReadableStreamLike, w as ResolvedClientConfig, S as SDK_PLATFORM, x as SDK_VERSION, y as ServerRequestIdSource, z as TransportDeps, T as TransportPort, U as UnknownFrame, G as UrgencyLevel, I as acceptedFrame, J as analysisCompleteFrame, K as analysisStartedFrame, L as assertNever, N as bufferedTextByteSource, O as buildBaseHeaders, P as checkPublishableKey, Q as createHttpTransport, V as deltaFrame, W as doneFrame, X as errorFrame, Y as errorFromResponse, Z as eventSourceByteSource, _ as eventSourceRequestId, $ as fetchByteSource, a0 as getGlobalFetch, a1 as heartbeatFrame, a2 as networkError, a3 as parseSse, a4 as requestIdOf, a5 as requestJson, a6 as requestRaw, a7 as resolveApiBaseUrl, a8 as resolveClientConfig, a9 as tryResolveApiBaseUrl, aa as tryResolveClientConfig, ab as unknownFrame } from '../config-BSjBdxrZ.cjs';
+export { B as Brand, C as ClientId, a as ConversationId, D as DocumentId, J as JobId, P as PetRef, R as RecordsRequestId, b as ResponseId, U as UserRef, _ as __brand, c as conversationId, p as petRef, u as unsafeClientId, d as unsafeConversationId, e as unsafeDocumentId, f as unsafeJobId, g as unsafePetRef, h as unsafeRecordsRequestId, i as unsafeResponseId, j as unsafeUserRef, k as userRef } from '../ids-CJ1S6adf.cjs';
+export { A as AuthContext, D as DeviceAuth, I as IdentityProvider, T as TokenProvider, a as authHeaders, b as authedSend, c as createIdentityProvider, n as newSessionId, w as withAuthHeaders } from '../identity-Brl-lDd6.cjs';
+export { C as CapabilityDecision, a as CapabilityDisabled, b as CapabilityName, D as DecideOptions, c as DisabledLevel, E as EntitlementDecision, L as LevelGrant, R as ResolvedEntitlements, d as decideCapability, e as deniedDecisionsFor, r as requires, f as resolveEntitlements } from '../resolve-Dq_4_agU.cjs';
+export { C as ClientBranding, E as ENTITLEMENTS_PATH, a as EVERFUR_DARK, b as EVERFUR_LIGHT, c as EntitlementResolution, d as EverfurColorTokens, e as EverfurFontWeight, f as EverfurLetterSpacingTokens, g as EverfurLineHeightTokens, h as EverfurMotionDurationTokens, i as EverfurMotionTokens, j as EverfurRadiusTokens, k as EverfurSpaceTokens, l as EverfurSpringToken, m as EverfurTextColorTokens, n as EverfurTheme, o as EverfurThemeMeta, p as EverfurTypeSizeTokens, q as EverfurTypeTokens, r as EverfurWeightTokens, F as FetchEntitlementsArgs, P as PET_AGE_YEARS_MAX, s as PET_BREED_MAX, t as PET_NAME_MAX, u as PET_SPECIES_MAX, v as PET_WEIGHT_KG_MAX, w as PetProfileInput, x as PetsRepository, R as RegisteredPet, y as ResolveThemeInput, z as createPetsRepository, A as deepFreeze, B as fetchEntitlements, D as hardenHttpsUrl, G as isEmptyBranding, H as parseClientBranding, I as parseColor, J as readableOn, K as resolveTheme, L as withServerBranding } from '../petsRepository-BEGb97M9.cjs';
+import '../requestFunnel-DuUH-kAe.cjs';
+
+/** Which wire shape a code arrives in. The two envelopes are different objects, not casings. */
+type ContractErrorEnvelope = "http_envelope" | "sse_frame";
+/** Every wire error code the contract declares, spelled EXACTLY as the server sends it. */
+type ContractWireErrorCode = "AccessDeniedException" | "AuthorizationException" | "ConflictException" | "DAILY_QUOTA_EXCEEDED" | "IDEMPOTENCY_KEY_IN_FLIGHT" | "IDEMPOTENCY_KEY_REUSED_DIFFERENT_REQUEST" | "InternalFailureException" | "NotImplementedException" | "PaymentRequiredException" | "ResourceNotFoundException" | "ServiceUnavailableException" | "TIER_UPGRADE_REQUIRED" | "ThrottlingException" | "ValidationException" | "accessDenied" | "authExpired" | "internal_error" | "invalidRequest" | "not_found" | "session_required" | "timeout" | "unavailable";
+
+/** One registry row, reduced to the facts the SDK needs at runtime. */
+interface ContractErrorRow {
+    /**
+     * The wire `code` string EXACTLY as the server sends it. Typed as `string`, not as the generated
+     * `ContractWireErrorCode` union: a row is looked up from a value that arrived off the network, and
+     * narrowing this field would push that unavoidable widening onto every caller.
+     */
+    readonly wireCode: string;
+    readonly envelope: ContractErrorEnvelope;
+    /** The registry's own retryable claim. Documentation of server semantics, not the SDK retry policy. */
+    readonly retryable: boolean;
+    /** The normalized taxonomy member this code folds to. */
+    readonly normalized: EverfurErrorCode;
+}
+/**
+ * Every code in the contract, joined to the member it folds to. Frozen.
+ *
+ * The wire code, its envelope and the server's own `retryable` claim are GENERATED (see the note above
+ * `NORMALIZED_FOLD`); only the fold is hand-written, and `Record<ContractWireErrorCode, ...>` makes it
+ * exhaustive, so a code added to the contract fails `tsc` here rather than silently becoming `unknown`.
+ */
+declare const CONTRACT_ERROR_ROWS: readonly ContractErrorRow[];
+/** The registry row for a raw wire code, or undefined when the code is not in the contract. */
+declare function contractErrorFor(wireCode: string | null | undefined): ContractErrorRow | undefined;
+/**
+ * The registry's `doc_url` for a row. SITE-RELATIVE by construction: the contract records that there is
+ * no confirmed public documentation host to prefix it with, so the SDK publishes the path and never
+ * fabricates an origin. The SSE frames are namespaced (`#sse-timeout`) because a frame code and an HTTP
+ * code can share a name; `tests/contract/errorRegistry.test.ts` asserts this derivation reproduces the
+ * registry's own `doc_url` for all 22 rows, so the pattern cannot drift unnoticed.
+ */
+declare function contractDocUrl(entry: ContractErrorRow): string;
+/**
+ * Is the `/errors` reference page actually published?
+ *
+ * Measured 2026-08-23: it is NOT. `everfur-frontend` has no `errors` route, so every `docUrl` the SDK
+ * emitted was a dangling pointer — a partner received the string `/errors#RATE_LIMITED`, with no origin to
+ * resolve it against and no page behind it if they guessed one. Handing out a link that cannot be opened is
+ * worse than handing out none: it reads as documentation that exists.
+ *
+ * `EverfurError.docUrl` is OPTIONAL and its own contract already says an unregistered code "simply yields
+ * no docUrl", so omitting it is contract-compatible rather than a breaking change.
+ *
+ * TO PUBLISH: add the route, set this to the origin (e.g. `'https://everfur.com'`), and `contractDocUrl`
+ * becomes an absolute URL. That is the whole change.
+ */
+declare const DOC_SITE_ORIGIN: string | null;
+/** The emitted `docUrl`, or null while no page exists to point at. */
+declare function publishedDocUrl(entry: ContractErrorRow): string | null;
+
+export { CONTRACT_ERROR_ROWS, type ContractErrorEnvelope, type ContractErrorRow, type ContractWireErrorCode, DOC_SITE_ORIGIN, EverfurErrorCode, contractDocUrl, contractErrorFor, publishedDocUrl };

package/dist/client/index.d.ts

@@ -0,0 +1,65 @@
+import { a as EverfurErrorCode } from '../EverfurResult-D92-uL82.js';
+export { A as AUTO_RETRYABLE_CODES, B as BACKOFF_BASE_MS, b as BACKOFF_CAP_MS, c as EVERFUR_ERROR_CATEGORIES, d as EVERFUR_ERROR_CODES, e as EverfurConfigError, f as EverfurError, g as EverfurErrorCategory, E as EverfurResult, h as EverfurThrownError, M as MAX_RETRY_ATTEMPTS, i as MakeEverfurErrorOptions, R as RETRYABLE_CONTRACT_CODES, j as backoffDelayMs, k as canRecreateOnNotFound, l as categoryFor, m as err, n as fromHttpStatus, o as fromWire, p as isAutoRetryable, q as isErr, r as isOk, s as isRetryableCode, t as makeEverfurError, u as ok, v as shouldRetry, w as unwrap, x as userFacingError } from '../EverfurResult-D92-uL82.js';
+export { A as AcceptedFrame, b as AnalysisCompleteFrame, c as AnalysisStartedFrame, B as ByteSource, C as ClientConfigFailure, d as ClientConfigFailureReason, e as ClientConfigOutcome, D as DEFAULT_CONTRACT_VERSION, f as DeltaFrame, g as DoneFrame, h as EMPTY_FRAME_ARRAYS, i as ENV_API_BASE_URL, j as ErrorFrame, k as EventSourceFactory, l as EventSourceInit, m as EventSourceLike, n as EventSourceMessage, o as EverfurConfig, E as EverfurRequest, p as EverfurRequestBase, q as FetchInit, a as FetchLike, r as FetchResponseLike, F as Frame, s as FrameBase, t as FrameKind, H as HeartbeatFrame, u as HttpMethod, M as MultipartBody, R as RawResponse, v as ReadableStreamLike, w as ResolvedClientConfig, S as SDK_PLATFORM, x as SDK_VERSION, y as ServerRequestIdSource, z as TransportDeps, T as TransportPort, U as UnknownFrame, G as UrgencyLevel, I as acceptedFrame, J as analysisCompleteFrame, K as analysisStartedFrame, L as assertNever, N as bufferedTextByteSource, O as buildBaseHeaders, P as checkPublishableKey, Q as createHttpTransport, V as deltaFrame, W as doneFrame, X as errorFrame, Y as errorFromResponse, Z as eventSourceByteSource, _ as eventSourceRequestId, $ as fetchByteSource, a0 as getGlobalFetch, a1 as heartbeatFrame, a2 as networkError, a3 as parseSse, a4 as requestIdOf, a5 as requestJson, a6 as requestRaw, a7 as resolveApiBaseUrl, a8 as resolveClientConfig, a9 as tryResolveApiBaseUrl, aa as tryResolveClientConfig, ab as unknownFrame } from '../config-CiJ0PVBB.js';
+export { B as Brand, C as ClientId, a as ConversationId, D as DocumentId, J as JobId, P as PetRef, R as RecordsRequestId, b as ResponseId, U as UserRef, _ as __brand, c as conversationId, p as petRef, u as unsafeClientId, d as unsafeConversationId, e as unsafeDocumentId, f as unsafeJobId, g as unsafePetRef, h as unsafeRecordsRequestId, i as unsafeResponseId, j as unsafeUserRef, k as userRef } from '../ids-CJ1S6adf.js';
+export { A as AuthContext, D as DeviceAuth, I as IdentityProvider, T as TokenProvider, a as authHeaders, b as authedSend, c as createIdentityProvider, n as newSessionId, w as withAuthHeaders } from '../identity-DK9zORrG.js';
+export { C as CapabilityDecision, a as CapabilityDisabled, b as CapabilityName, D as DecideOptions, c as DisabledLevel, E as EntitlementDecision, L as LevelGrant, R as ResolvedEntitlements, d as decideCapability, e as deniedDecisionsFor, r as requires, f as resolveEntitlements } from '../resolve-Dq_4_agU.js';
+export { C as ClientBranding, E as ENTITLEMENTS_PATH, a as EVERFUR_DARK, b as EVERFUR_LIGHT, c as EntitlementResolution, d as EverfurColorTokens, e as EverfurFontWeight, f as EverfurLetterSpacingTokens, g as EverfurLineHeightTokens, h as EverfurMotionDurationTokens, i as EverfurMotionTokens, j as EverfurRadiusTokens, k as EverfurSpaceTokens, l as EverfurSpringToken, m as EverfurTextColorTokens, n as EverfurTheme, o as EverfurThemeMeta, p as EverfurTypeSizeTokens, q as EverfurTypeTokens, r as EverfurWeightTokens, F as FetchEntitlementsArgs, P as PET_AGE_YEARS_MAX, s as PET_BREED_MAX, t as PET_NAME_MAX, u as PET_SPECIES_MAX, v as PET_WEIGHT_KG_MAX, w as PetProfileInput, x as PetsRepository, R as RegisteredPet, y as ResolveThemeInput, z as createPetsRepository, A as deepFreeze, B as fetchEntitlements, D as hardenHttpsUrl, G as isEmptyBranding, H as parseClientBranding, I as parseColor, J as readableOn, K as resolveTheme, L as withServerBranding } from '../petsRepository-Bu18r2kK.js';
+import '../requestFunnel-dio5OmR9.js';
+
+/** Which wire shape a code arrives in. The two envelopes are different objects, not casings. */
+type ContractErrorEnvelope = "http_envelope" | "sse_frame";
+/** Every wire error code the contract declares, spelled EXACTLY as the server sends it. */
+type ContractWireErrorCode = "AccessDeniedException" | "AuthorizationException" | "ConflictException" | "DAILY_QUOTA_EXCEEDED" | "IDEMPOTENCY_KEY_IN_FLIGHT" | "IDEMPOTENCY_KEY_REUSED_DIFFERENT_REQUEST" | "InternalFailureException" | "NotImplementedException" | "PaymentRequiredException" | "ResourceNotFoundException" | "ServiceUnavailableException" | "TIER_UPGRADE_REQUIRED" | "ThrottlingException" | "ValidationException" | "accessDenied" | "authExpired" | "internal_error" | "invalidRequest" | "not_found" | "session_required" | "timeout" | "unavailable";
+
+/** One registry row, reduced to the facts the SDK needs at runtime. */
+interface ContractErrorRow {
+    /**
+     * The wire `code` string EXACTLY as the server sends it. Typed as `string`, not as the generated
+     * `ContractWireErrorCode` union: a row is looked up from a value that arrived off the network, and
+     * narrowing this field would push that unavoidable widening onto every caller.
+     */
+    readonly wireCode: string;
+    readonly envelope: ContractErrorEnvelope;
+    /** The registry's own retryable claim. Documentation of server semantics, not the SDK retry policy. */
+    readonly retryable: boolean;
+    /** The normalized taxonomy member this code folds to. */
+    readonly normalized: EverfurErrorCode;
+}
+/**
+ * Every code in the contract, joined to the member it folds to. Frozen.
+ *
+ * The wire code, its envelope and the server's own `retryable` claim are GENERATED (see the note above
+ * `NORMALIZED_FOLD`); only the fold is hand-written, and `Record<ContractWireErrorCode, ...>` makes it
+ * exhaustive, so a code added to the contract fails `tsc` here rather than silently becoming `unknown`.
+ */
+declare const CONTRACT_ERROR_ROWS: readonly ContractErrorRow[];
+/** The registry row for a raw wire code, or undefined when the code is not in the contract. */
+declare function contractErrorFor(wireCode: string | null | undefined): ContractErrorRow | undefined;
+/**
+ * The registry's `doc_url` for a row. SITE-RELATIVE by construction: the contract records that there is
+ * no confirmed public documentation host to prefix it with, so the SDK publishes the path and never
+ * fabricates an origin. The SSE frames are namespaced (`#sse-timeout`) because a frame code and an HTTP
+ * code can share a name; `tests/contract/errorRegistry.test.ts` asserts this derivation reproduces the
+ * registry's own `doc_url` for all 22 rows, so the pattern cannot drift unnoticed.
+ */
+declare function contractDocUrl(entry: ContractErrorRow): string;
+/**
+ * Is the `/errors` reference page actually published?
+ *
+ * Measured 2026-08-23: it is NOT. `everfur-frontend` has no `errors` route, so every `docUrl` the SDK
+ * emitted was a dangling pointer — a partner received the string `/errors#RATE_LIMITED`, with no origin to
+ * resolve it against and no page behind it if they guessed one. Handing out a link that cannot be opened is
+ * worse than handing out none: it reads as documentation that exists.
+ *
+ * `EverfurError.docUrl` is OPTIONAL and its own contract already says an unregistered code "simply yields
+ * no docUrl", so omitting it is contract-compatible rather than a breaking change.
+ *
+ * TO PUBLISH: add the route, set this to the origin (e.g. `'https://everfur.com'`), and `contractDocUrl`
+ * becomes an absolute URL. That is the whole change.
+ */
+declare const DOC_SITE_ORIGIN: string | null;
+/** The emitted `docUrl`, or null while no page exists to point at. */
+declare function publishedDocUrl(entry: ContractErrorRow): string | null;
+
+export { CONTRACT_ERROR_ROWS, type ContractErrorEnvelope, type ContractErrorRow, type ContractWireErrorCode, DOC_SITE_ORIGIN, EverfurErrorCode, contractDocUrl, contractErrorFor, publishedDocUrl };