@everfur/sdk 0.1.1 → 0.4.0

package/dist/useVetVisit-Bc84hWUU.d.cts

@@ -0,0 +1,187 @@
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.cjs';
+import { P as PetRef } from './ids-B2GAAifq.cjs';
+import { V as VetVisitIntent } from './visitIntent-D7_yVp1I.cjs';
+
+/** What the hosted page will open for a handoff minted with `visitRef`: the platform's own echo. */
+interface VetVisitHandoffVisit {
+    /** The visit reference the handoff was minted for, as you sent it. */
+    readonly visitRef: string;
+    /** What the hosted page opens for it. `visit` when you named no intent. */
+    readonly intent: VetVisitIntent;
+}
+/** A minted handoff. Open `url` once, promptly; it expires at `expiresAt` and is spent by the first use. */
+interface VetVisitHandoff {
+    /** The hosted Everfur page with the single-use token in its fragment. Never log or persist it. */
+    readonly url: string;
+    /** ISO-8601 timestamp from the server; about 120 seconds after the mint. */
+    readonly expiresAt: string;
+    /**
+     * Present only when the handoff was minted with `returnTo`: the opaque id the user comes back with on your
+     * registered return destination. Keep it to match the return (`parseVetVisitReturn`). It says nothing about
+     * the visit.
+     */
+    readonly flowId?: string;
+    /**
+     * Present only when the handoff was minted with `visitRef`: what the hosted page will open, echoed by the
+     * platform from what it stored with the handoff. The reference never rides the URL, so this is the only
+     * place to read it back. Absent on an ordinary booking handoff.
+     */
+    readonly visit?: VetVisitHandoffVisit;
+}
+/** Where a vet visit was opened from. `'chat'`: the user chose it inside partner Chat, for the chat's pet. */
+type VetVisitEntry = 'chat';
+/** Optional handoff settings. */
+interface VetVisitHandoffOptions {
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. After the hosted visit flow the user
+     * can go back to that destination, and only that one. Never a URL.
+     */
+    readonly returnTo?: string | null;
+    /** `'chat'` when the user opened the visit from Chat. Requires the pet the chat is about. */
+    readonly entry?: VetVisitEntry | null;
+    /**
+     * TV-01. The reference of a visit this member ALREADY has (the `visit_ref` the `visit.*` events carry, and
+     * the one `parseEverfurNotification` reads off a tapped push). The handoff then opens that visit instead of
+     * the booking funnel. Everfur resolves it at the mint against this member's own live link, so a reference
+     * that is not theirs is refused with the same words a malformed one gets: a `validationFailed` you cannot
+     * probe for visits with. At most 64 characters.
+     */
+    readonly visitRef?: string | null;
+    /**
+     * What to open for `visitRef`: the visit itself, its call, its summary or its messages. Absent means
+     * `visit`. An intent with no `visitRef` is refused locally, because it names a route with nothing to route
+     * to. A tapped push already carries the right one on `target.intent`.
+     */
+    readonly intent?: VetVisitIntent | null;
+}
+/** The state preflight's whole answer. Nothing about the account, the plan or the price. */
+interface VetVisitAvailability {
+    /** True when a vet visit can be booked for the state asked about. False for every other reason, alike. */
+    readonly available: boolean;
+}
+/** A partner app's return from the hosted visit flow, read by `parseVetVisitReturn`. Only the flow id. */
+interface VetVisitReturn {
+    /** The opaque flow id from the handoff that led to this return. */
+    readonly flowId: string;
+}
+/**
+ * The closed set a partner branches on, derived from the route's documented outcomes.
+ *
+ * - `sessionRequired`: the integration sent no signed session. Mint one on your backend
+ *   (`@everfur/sdk/server` mintPartnerSession) and hand the token to `EverfurUser.getToken`.
+ * - `authRejected`: the session token was refused after the one refresh the SDK performs.
+ * - `accessDenied`: a signed session whose key or plan does not include vet visits.
+ * - `unavailable`: vet visits are off for this partner or for Everfur right now (the route answers 404).
+ * - `rateLimited`: this user or this partner has opened too many visits recently. Do not retry in a loop.
+ * - `sdkUpdateRequired`: the API refused this SDK version.
+ * - `invalidRequest`: the pet reference was refused (empty, or longer than 128 characters).
+ * - `network`: no response arrived (offline, DNS, timeout).
+ * - `serverError`: the API failed, or answered with something that is not a usable Everfur visit URL.
+ * - `popupBlocked`: web only. The browser refused to open the new tab.
+ * - `openFailed`: React Native only. The host could not open the URL.
+ * - `cancelled`: nothing to show. The visit tab was closed before it loaded, or the signed-in user changed
+ *   while the handoff was being minted, so it was dropped rather than opened for the previous user.
+ * - `unknown`: anything else.
+ */
+type VetVisitErrorReason = 'sessionRequired' | 'authRejected' | 'accessDenied' | 'unavailable' | 'rateLimited' | 'sdkUpdateRequired' | 'invalidRequest' | 'network' | 'serverError' | 'popupBlocked' | 'openFailed' | 'cancelled' | 'unknown';
+/** Map a settled handoff failure to its closed reason. Total and pure. */
+declare function vetVisitErrorReasonOf(error: EverfurError): VetVisitErrorReason;
+/** Mints handoffs for the current session. Built by `useVetVisit`; injectable for tests. */
+interface VetVisitController {
+    /**
+     * Mint one handoff. Optional `petRef` scopes the visit to the partner's pet, shown to the user after
+     * sign-in. `options` names a registered return destination and where the visit was opened from. Settles;
+     * never throws; never retries.
+     */
+    createHandoff(petRef?: PetRef | null, options?: VetVisitHandoffOptions): Promise<EverfurResult<VetVisitHandoff>>;
+    /**
+     * Ask whether a vet visit is available for a US state (for example `'CA'`). Settles. An injected controller
+     * without it is treated as unavailable wherever the hook needs the answer.
+     */
+    checkAvailability?(state: string): Promise<EverfurResult<VetVisitAvailability>>;
+    /** True only while Everfur has the vet entry inside Chat switched on. Never throws; any failure is false. */
+    chatEntryOpen?(): Promise<boolean>;
+}
+/**
+ * Read an Everfur return off the URL your registered return destination was opened with. Returns the opaque
+ * flow id you received from the handoff, or null for any URL that does not carry exactly one well-formed
+ * Everfur flow id in its query. It carries nothing about the visit, the pet or the account.
+ */
+declare function parseVetVisitReturn(url: string): VetVisitReturn | null;
+
+/** `idle` before a tap and after a successful open; `opening` while the handoff is minted; `error` after a failure. */
+type VetVisitStatus = 'idle' | 'opening' | 'error';
+/** What one `open()` call settled to. The URL is deliberately absent. */
+type VetVisitOpenResult = {
+    readonly opened: true;
+    readonly flowId?: string;
+} | {
+    readonly opened: false;
+    readonly reason: VetVisitErrorReason;
+    readonly error: EverfurError | null;
+};
+/** Options for `useVetVisit`. */
+interface UseVetVisitOptions {
+    /** The partner's pet reference to scope the visit to. `open(petRef)` overrides it per call. */
+    readonly petRef?: PetRef | null;
+    /** Host/test seam: inject a controller instead of building one from the provider's session. */
+    readonly controller?: VetVisitController;
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. The visit can then send the user back
+     * to it, and `open()` settles with the `flowId` that return will carry.
+     */
+    readonly returnTo?: string | null;
+    /**
+     * The user's US state (for example `'CA'`). When set, `available` stays false until Everfur confirms a visit
+     * is available there, so the entry is never shown to a user who could not book.
+     */
+    readonly usState?: string | null;
+    /**
+     * `'chat'` for the entry inside Chat. `available` then also needs Everfur's chat entry switch and a pet (the
+     * one the chat is about); the visit itself is the same hosted visit.
+     */
+    readonly entry?: VetVisitEntry | null;
+}
+/** What `useVetVisit` returns. The handoff URL is never part of it. */
+interface UseVetVisitState {
+    /**
+     * True only when the server grants the `televet` capability AND the provider is scoped to a user. A handoff
+     * is minted from the user's session, so a publishable-key-only context could only ever spend a blank tab on
+     * a `sessionRequired` failure. A surface renders nothing otherwise.
+     */
+    readonly available: boolean;
+    /** True while the capability verdict is still resolving. */
+    readonly isPending: boolean;
+    /** Where the last `open()` is: idle, opening, or failed. */
+    readonly status: VetVisitStatus;
+    /** The settled failure of the last `open()`, or null. `error.displayMessage` is safe to show. */
+    readonly error: EverfurError | null;
+    /** The closed reason for the last failure, or null. */
+    readonly errorReason: VetVisitErrorReason | null;
+    /**
+     * Mint a handoff and open the hosted Everfur visit. Call it directly from a press or click handler. A second
+     * call while one is in flight returns the same promise rather than minting a second handoff.
+     */
+    open(petRef?: PetRef | null): Promise<VetVisitOpenResult>;
+    /**
+     * TV-01. Open a visit this member ALREADY has, instead of the booking funnel: the recap of a finished
+     * visit, the thread the vet wrote in, the call a reminder is for. `visitRef` is the reference the
+     * `visit.*` events carry, and `intent` is what to open for it (`visit` when omitted).
+     *
+     * Hand it what a tapped push gave you, unchanged:
+     * ```ts
+     * const n = parseEverfurNotification(response);
+     * if (n?.target.kind === 'visit' && n.target.intent !== null) {
+     *   await visit.openVisit(n.target.visitRef, n.target.intent);
+     * }
+     * ```
+     * A `null` intent on a target means the visit is over without happening (cancelled, missed): there is
+     * nothing left to open, so call `open()` to book a new one instead.
+     *
+     * Everfur resolves the reference at the mint against this member's own visits, so one that is not theirs
+     * settles `invalidRequest` and opens nothing. Shares the single-flight rule with `open`.
+     */
+    openVisit(visitRef: string, intent?: VetVisitIntent | null): Promise<VetVisitOpenResult>;
+}
+
+export { type UseVetVisitOptions as U, type VetVisitEntry as V, type UseVetVisitState as a, type VetVisitErrorReason as b, type VetVisitController as c, type VetVisitAvailability as d, type VetVisitHandoff as e, type VetVisitHandoffOptions as f, type VetVisitHandoffVisit as g, type VetVisitOpenResult as h, type VetVisitReturn as i, type VetVisitStatus as j, parseVetVisitReturn as p, vetVisitErrorReasonOf as v };

package/dist/useVetVisit-CjmMa896.d.ts

@@ -0,0 +1,187 @@
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.js';
+import { P as PetRef } from './ids-B2GAAifq.js';
+import { V as VetVisitIntent } from './visitIntent-D7_yVp1I.js';
+
+/** What the hosted page will open for a handoff minted with `visitRef`: the platform's own echo. */
+interface VetVisitHandoffVisit {
+    /** The visit reference the handoff was minted for, as you sent it. */
+    readonly visitRef: string;
+    /** What the hosted page opens for it. `visit` when you named no intent. */
+    readonly intent: VetVisitIntent;
+}
+/** A minted handoff. Open `url` once, promptly; it expires at `expiresAt` and is spent by the first use. */
+interface VetVisitHandoff {
+    /** The hosted Everfur page with the single-use token in its fragment. Never log or persist it. */
+    readonly url: string;
+    /** ISO-8601 timestamp from the server; about 120 seconds after the mint. */
+    readonly expiresAt: string;
+    /**
+     * Present only when the handoff was minted with `returnTo`: the opaque id the user comes back with on your
+     * registered return destination. Keep it to match the return (`parseVetVisitReturn`). It says nothing about
+     * the visit.
+     */
+    readonly flowId?: string;
+    /**
+     * Present only when the handoff was minted with `visitRef`: what the hosted page will open, echoed by the
+     * platform from what it stored with the handoff. The reference never rides the URL, so this is the only
+     * place to read it back. Absent on an ordinary booking handoff.
+     */
+    readonly visit?: VetVisitHandoffVisit;
+}
+/** Where a vet visit was opened from. `'chat'`: the user chose it inside partner Chat, for the chat's pet. */
+type VetVisitEntry = 'chat';
+/** Optional handoff settings. */
+interface VetVisitHandoffOptions {
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. After the hosted visit flow the user
+     * can go back to that destination, and only that one. Never a URL.
+     */
+    readonly returnTo?: string | null;
+    /** `'chat'` when the user opened the visit from Chat. Requires the pet the chat is about. */
+    readonly entry?: VetVisitEntry | null;
+    /**
+     * TV-01. The reference of a visit this member ALREADY has (the `visit_ref` the `visit.*` events carry, and
+     * the one `parseEverfurNotification` reads off a tapped push). The handoff then opens that visit instead of
+     * the booking funnel. Everfur resolves it at the mint against this member's own live link, so a reference
+     * that is not theirs is refused with the same words a malformed one gets: a `validationFailed` you cannot
+     * probe for visits with. At most 64 characters.
+     */
+    readonly visitRef?: string | null;
+    /**
+     * What to open for `visitRef`: the visit itself, its call, its summary or its messages. Absent means
+     * `visit`. An intent with no `visitRef` is refused locally, because it names a route with nothing to route
+     * to. A tapped push already carries the right one on `target.intent`.
+     */
+    readonly intent?: VetVisitIntent | null;
+}
+/** The state preflight's whole answer. Nothing about the account, the plan or the price. */
+interface VetVisitAvailability {
+    /** True when a vet visit can be booked for the state asked about. False for every other reason, alike. */
+    readonly available: boolean;
+}
+/** A partner app's return from the hosted visit flow, read by `parseVetVisitReturn`. Only the flow id. */
+interface VetVisitReturn {
+    /** The opaque flow id from the handoff that led to this return. */
+    readonly flowId: string;
+}
+/**
+ * The closed set a partner branches on, derived from the route's documented outcomes.
+ *
+ * - `sessionRequired`: the integration sent no signed session. Mint one on your backend
+ *   (`@everfur/sdk/server` mintPartnerSession) and hand the token to `EverfurUser.getToken`.
+ * - `authRejected`: the session token was refused after the one refresh the SDK performs.
+ * - `accessDenied`: a signed session whose key or plan does not include vet visits.
+ * - `unavailable`: vet visits are off for this partner or for Everfur right now (the route answers 404).
+ * - `rateLimited`: this user or this partner has opened too many visits recently. Do not retry in a loop.
+ * - `sdkUpdateRequired`: the API refused this SDK version.
+ * - `invalidRequest`: the pet reference was refused (empty, or longer than 128 characters).
+ * - `network`: no response arrived (offline, DNS, timeout).
+ * - `serverError`: the API failed, or answered with something that is not a usable Everfur visit URL.
+ * - `popupBlocked`: web only. The browser refused to open the new tab.
+ * - `openFailed`: React Native only. The host could not open the URL.
+ * - `cancelled`: nothing to show. The visit tab was closed before it loaded, or the signed-in user changed
+ *   while the handoff was being minted, so it was dropped rather than opened for the previous user.
+ * - `unknown`: anything else.
+ */
+type VetVisitErrorReason = 'sessionRequired' | 'authRejected' | 'accessDenied' | 'unavailable' | 'rateLimited' | 'sdkUpdateRequired' | 'invalidRequest' | 'network' | 'serverError' | 'popupBlocked' | 'openFailed' | 'cancelled' | 'unknown';
+/** Map a settled handoff failure to its closed reason. Total and pure. */
+declare function vetVisitErrorReasonOf(error: EverfurError): VetVisitErrorReason;
+/** Mints handoffs for the current session. Built by `useVetVisit`; injectable for tests. */
+interface VetVisitController {
+    /**
+     * Mint one handoff. Optional `petRef` scopes the visit to the partner's pet, shown to the user after
+     * sign-in. `options` names a registered return destination and where the visit was opened from. Settles;
+     * never throws; never retries.
+     */
+    createHandoff(petRef?: PetRef | null, options?: VetVisitHandoffOptions): Promise<EverfurResult<VetVisitHandoff>>;
+    /**
+     * Ask whether a vet visit is available for a US state (for example `'CA'`). Settles. An injected controller
+     * without it is treated as unavailable wherever the hook needs the answer.
+     */
+    checkAvailability?(state: string): Promise<EverfurResult<VetVisitAvailability>>;
+    /** True only while Everfur has the vet entry inside Chat switched on. Never throws; any failure is false. */
+    chatEntryOpen?(): Promise<boolean>;
+}
+/**
+ * Read an Everfur return off the URL your registered return destination was opened with. Returns the opaque
+ * flow id you received from the handoff, or null for any URL that does not carry exactly one well-formed
+ * Everfur flow id in its query. It carries nothing about the visit, the pet or the account.
+ */
+declare function parseVetVisitReturn(url: string): VetVisitReturn | null;
+
+/** `idle` before a tap and after a successful open; `opening` while the handoff is minted; `error` after a failure. */
+type VetVisitStatus = 'idle' | 'opening' | 'error';
+/** What one `open()` call settled to. The URL is deliberately absent. */
+type VetVisitOpenResult = {
+    readonly opened: true;
+    readonly flowId?: string;
+} | {
+    readonly opened: false;
+    readonly reason: VetVisitErrorReason;
+    readonly error: EverfurError | null;
+};
+/** Options for `useVetVisit`. */
+interface UseVetVisitOptions {
+    /** The partner's pet reference to scope the visit to. `open(petRef)` overrides it per call. */
+    readonly petRef?: PetRef | null;
+    /** Host/test seam: inject a controller instead of building one from the provider's session. */
+    readonly controller?: VetVisitController;
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. The visit can then send the user back
+     * to it, and `open()` settles with the `flowId` that return will carry.
+     */
+    readonly returnTo?: string | null;
+    /**
+     * The user's US state (for example `'CA'`). When set, `available` stays false until Everfur confirms a visit
+     * is available there, so the entry is never shown to a user who could not book.
+     */
+    readonly usState?: string | null;
+    /**
+     * `'chat'` for the entry inside Chat. `available` then also needs Everfur's chat entry switch and a pet (the
+     * one the chat is about); the visit itself is the same hosted visit.
+     */
+    readonly entry?: VetVisitEntry | null;
+}
+/** What `useVetVisit` returns. The handoff URL is never part of it. */
+interface UseVetVisitState {
+    /**
+     * True only when the server grants the `televet` capability AND the provider is scoped to a user. A handoff
+     * is minted from the user's session, so a publishable-key-only context could only ever spend a blank tab on
+     * a `sessionRequired` failure. A surface renders nothing otherwise.
+     */
+    readonly available: boolean;
+    /** True while the capability verdict is still resolving. */
+    readonly isPending: boolean;
+    /** Where the last `open()` is: idle, opening, or failed. */
+    readonly status: VetVisitStatus;
+    /** The settled failure of the last `open()`, or null. `error.displayMessage` is safe to show. */
+    readonly error: EverfurError | null;
+    /** The closed reason for the last failure, or null. */
+    readonly errorReason: VetVisitErrorReason | null;
+    /**
+     * Mint a handoff and open the hosted Everfur visit. Call it directly from a press or click handler. A second
+     * call while one is in flight returns the same promise rather than minting a second handoff.
+     */
+    open(petRef?: PetRef | null): Promise<VetVisitOpenResult>;
+    /**
+     * TV-01. Open a visit this member ALREADY has, instead of the booking funnel: the recap of a finished
+     * visit, the thread the vet wrote in, the call a reminder is for. `visitRef` is the reference the
+     * `visit.*` events carry, and `intent` is what to open for it (`visit` when omitted).
+     *
+     * Hand it what a tapped push gave you, unchanged:
+     * ```ts
+     * const n = parseEverfurNotification(response);
+     * if (n?.target.kind === 'visit' && n.target.intent !== null) {
+     *   await visit.openVisit(n.target.visitRef, n.target.intent);
+     * }
+     * ```
+     * A `null` intent on a target means the visit is over without happening (cancelled, missed): there is
+     * nothing left to open, so call `open()` to book a new one instead.
+     *
+     * Everfur resolves the reference at the mint against this member's own visits, so one that is not theirs
+     * settles `invalidRequest` and opens nothing. Shares the single-flight rule with `open`.
+     */
+    openVisit(visitRef: string, intent?: VetVisitIntent | null): Promise<VetVisitOpenResult>;
+}
+
+export { type UseVetVisitOptions as U, type VetVisitEntry as V, type UseVetVisitState as a, type VetVisitErrorReason as b, type VetVisitController as c, type VetVisitAvailability as d, type VetVisitHandoff as e, type VetVisitHandoffOptions as f, type VetVisitHandoffVisit as g, type VetVisitOpenResult as h, type VetVisitReturn as i, type VetVisitStatus as j, parseVetVisitReturn as p, vetVisitErrorReasonOf as v };