@everfur/sdk 0.12.0 → 0.13.0

package/dist/idempotency.d-WpXx9zQo.d.ts

@@ -0,0 +1,910 @@
+import { j as FetchLike } from './config.d-Dy6igYlH.js';
+
+type OmsError = 
+/** 404: hidden. The shop, the gate, the record, or the account is not available to this viewer. */
+{
+    readonly kind: 'unavailable';
+    readonly requestId?: string;
+}
+/** The host's `getToken` returned nothing or failed (or a gateway answered 401): no request was sent. */
+ | {
+    readonly kind: 'signedOut';
+}
+/** 402, 409, 422: a business refusal the customer can act on. */
+ | {
+    readonly kind: 'refused';
+    readonly status: 402 | 409 | 422;
+    readonly reasonCode: string | null;
+    /** The contract's product copy, safe to show; null when absent. */
+    readonly message: string | null;
+    readonly requestId?: string;
+}
+/** 400: the SDK sent something the server would not take (a bug), or a local check refused it first. */
+ | {
+    readonly kind: 'invalidRequest';
+    readonly requestId?: string;
+}
+/** 429: past the per-user hourly limit on checkout, pay or card setup. */
+ | {
+    readonly kind: 'rateLimited';
+    readonly retryAfterSeconds: number | null;
+    readonly requestId?: string;
+}
+/** 503: a dependency (pharmacy, Stripe, database) is down. Retry later. */
+ | {
+    readonly kind: 'serviceUnavailable';
+    readonly requestId?: string;
+}
+/** 500 or any other status. */
+ | {
+    readonly kind: 'serverError';
+    readonly status: number;
+    readonly requestId?: string;
+}
+/** The request never got an answer (offline, DNS, CORS). */
+ | {
+    readonly kind: 'network';
+}
+/** The request ran past the SDK's deadline. */
+ | {
+    readonly kind: 'timeout';
+}
+/** A 2xx answer the SDK could not read (a field missing or of the wrong type). */
+ | {
+    readonly kind: 'badResponse';
+    readonly requestId?: string;
+};
+type OmsResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: OmsError;
+};
+/** True for a refusal with this `reason_code`. */
+declare function isOmsRefusal(error: OmsError, reasonCode?: string): boolean;
+/** True when the answer means "this is not for this viewer": hide it, never show an error. */
+declare function isOmsUnavailable(error: OmsError): boolean;
+/** Worth one more try by the same user action (with the SAME idempotency key). */
+declare function isOmsRetryable(error: OmsError): boolean;
+
+/** Integer cents, USD (`4599` is $45.99). Never a float. */
+type OmsCents = number;
+type OmsDeliverySpeed = 'ground' | 'two_day' | 'next_day';
+/** `GET /oms/shop-config`. Each null hides one feature (contract 4.17). */
+interface OmsShopConfig {
+    /** Null hides auto-ship (plans). */
+    readonly recurringTermsVersion: string | null;
+    readonly recurringTermsUrl: string | null;
+    /** Null hides card entry. */
+    readonly stripePublishableKey: string | null;
+    /** Null means the shop's terms are not written yet: a quote would answer 409. */
+    readonly delivery: {
+        readonly firstFill: OmsDeliverySpeed | null;
+        readonly refill: OmsDeliverySpeed | null;
+    } | null;
+}
+type OmsPackUnit = 'each' | 'gram' | 'milliliter';
+/** One active offer (contract 4.1). */
+interface OmsOffer {
+    readonly offerId: string;
+    readonly sku: string;
+    readonly title: string;
+    readonly fulfillmentType: string;
+    readonly requiresRx: boolean;
+    readonly compounded: boolean;
+    /** A decimal string ("30"), or null. */
+    readonly packQuantity: string | null;
+    readonly packUnit: OmsPackUnit | null;
+    /** One unit before any discount; null until the shop's commercial terms are written (contract 8.1). */
+    readonly price: OmsCents | null;
+}
+interface OmsOfferPage {
+    readonly offers: readonly OmsOffer[];
+    /** Pass back as `cursor`; null is the last page. */
+    readonly nextCursor: string | null;
+}
+/** A cart or plan line. A prescription line names the pet and the prescription (contract 3.5). */
+interface OmsCartLine {
+    readonly offerId: string;
+    /** 1 to 99. */
+    readonly quantity: number;
+    readonly petId?: string;
+    readonly rxId?: string;
+}
+interface OmsQuoteLine {
+    readonly offerId: string;
+    readonly quantity: number;
+    readonly petId: string | null;
+    readonly unitPrice: OmsCents;
+    readonly discount: OmsCents;
+    readonly tax: OmsCents;
+}
+/** `POST /oms/cart/quote`. Creates nothing; good for 30 minutes. */
+interface OmsQuote {
+    readonly lines: readonly OmsQuoteLine[];
+    readonly shipping: OmsCents;
+    readonly tax: OmsCents;
+    readonly total: OmsCents;
+    readonly expiresAt: string;
+}
+type OmsCheckoutState = 'draft' | 'authorizing' | 'confirmed' | 'compensating' | 'failed' | 'expired';
+/** `POST /oms/checkouts` (201). `total` is what confirm will charge. */
+interface OmsCheckout {
+    readonly checkoutId: string;
+    readonly state: OmsCheckoutState | string;
+    readonly orderIds: readonly string[];
+    readonly createdAt: string;
+    readonly total: OmsCents;
+    readonly shipping: OmsCents;
+    readonly tax: OmsCents;
+}
+interface OmsResaleOutcome {
+    readonly outcome: 'confirmed' | 'action_required';
+    readonly orderId: string;
+    /** A Stripe PaymentIntent client secret when `action_required` (3-D Secure); null when confirmed. */
+    readonly payerAction: string | null;
+}
+/** `POST /oms/checkouts/{id}/confirm`. */
+interface OmsConfirmation {
+    readonly checkoutId: string;
+    readonly resale: readonly OmsResaleOutcome[];
+}
+type OmsOrderStatus = 'pending_placement' | 'placement_unknown' | 'placed' | 'accepted' | 'release_sent' | 'release_unknown' | 'released' | 'shipped' | 'delivered' | 'needs_support' | 'rejected' | 'cancelled' | 'pending_handoff';
+interface OmsOrderSummary {
+    readonly orderId: string;
+    /** The number the customer sees (`EF-26-0004817`); null until placed. */
+    readonly referenceNumber: string | null;
+    /** One of `OmsOrderStatus`; an unknown future value is carried as sent. */
+    readonly status: OmsOrderStatus | string;
+    readonly total: OmsCents;
+    readonly placedAt: string | null;
+}
+interface OmsOrderPage {
+    readonly orders: readonly OmsOrderSummary[];
+    readonly nextCursor: string | null;
+}
+interface OmsOrderLine {
+    readonly lineId: string;
+    readonly offerId: string;
+    readonly sku: string;
+    readonly title: string;
+    readonly requiresRx: boolean;
+    readonly compounded: boolean;
+    readonly packQuantity: string | null;
+    readonly packUnit: OmsPackUnit | null;
+    readonly quantity: number;
+    readonly unitPrice: OmsCents;
+    readonly discount: OmsCents;
+    readonly tax: OmsCents;
+    readonly fulfillmentType: string;
+    readonly petId: string | null;
+}
+type OmsShipmentState = 'label_created' | 'in_transit' | 'exception' | 'delivered' | 'returned_to_sender';
+interface OmsTrackingEvent {
+    readonly carrier: string | null;
+    readonly trackingNumber: string | null;
+    readonly status: OmsShipmentState | string;
+    readonly occurredAt: string | null;
+    /** An https link, else null (contract 8.3). */
+    readonly trackingUrl: string | null;
+    /** A date, or null. */
+    readonly deliveryBy: string | null;
+}
+interface OmsShipment {
+    readonly shipmentId: string;
+    readonly state: OmsShipmentState | string;
+    readonly lines: readonly {
+        readonly lineId: string;
+        readonly quantity: number;
+    }[];
+    readonly tracking: readonly OmsTrackingEvent[];
+}
+type OmsPaymentStatus = 'processing' | 'requires_action' | 'authorized' | 'captured' | 'voided' | 'expired' | 'failed';
+interface OmsRefund {
+    readonly refundId: string;
+    readonly amount: OmsCents;
+    readonly state: string;
+}
+/** `GET /oms/orders/{id}`. */
+interface OmsOrder {
+    readonly summary: OmsOrderSummary;
+    readonly lines: readonly OmsOrderLine[];
+    readonly shipping: OmsCents;
+    readonly shippingTax: OmsCents;
+    readonly shipments: readonly OmsShipment[];
+    readonly canCancel: boolean;
+    readonly canReturn: boolean;
+    readonly canPay: boolean;
+    readonly paymentStatus: OmsPaymentStatus | string | null;
+    readonly refunds: readonly OmsRefund[];
+    readonly returnIds: readonly string[];
+}
+interface OmsCancelOutcome {
+    readonly outcome: 'cancelled' | 'requested' | 'not_cancellable' | string;
+    /** Cents given back when cancelled (0 when only a hold was voided). */
+    readonly refunded: OmsCents | null;
+    /** `too_late` or `cancel_with_partner` when not cancellable. */
+    readonly reasonCode: string | null;
+}
+interface OmsPayOutcome {
+    readonly outcome: 'authorized' | 'action_required';
+    readonly orderId: string;
+    readonly payerAction: string | null;
+}
+interface OmsReturnLine {
+    readonly lineId: string;
+    readonly quantity: number;
+    readonly reasonCode: string;
+}
+interface OmsReturn {
+    readonly returnId: string;
+    readonly orderId: string;
+    readonly lines: readonly OmsReturnLine[];
+    readonly state: string;
+    readonly rma: string | null;
+    readonly labelUrl: string | null;
+}
+interface OmsCase {
+    readonly caseId: string;
+    readonly orderId: string;
+    readonly reasonCode: string;
+    readonly message: string;
+    readonly openedAt: string;
+    readonly closedAt: string | null;
+}
+type OmsPrescriptionStatus = 'ready' | 'being_prepared' | 'too_soon' | 'refills_used' | 'expired';
+/** `GET /oms/prescriptions` (contract 4.12). */
+interface OmsPrescription {
+    readonly rxId: string;
+    readonly petId: string;
+    readonly drug: string;
+    readonly strength: string | null;
+    readonly form: string | null;
+    readonly status: OmsPrescriptionStatus | string;
+    /** Set when `ready`. */
+    readonly offerId: string | null;
+    readonly packCount: number | null;
+    readonly fillsUsed: number | null;
+    readonly fillsTotal: number | null;
+    readonly expiresOn: string | null;
+    /** Set when `too_soon`. */
+    readonly nextFillOn: string | null;
+}
+/** A saved address, as listed: a label only, the address is sealed at rest (contract 4.13). */
+interface OmsAddressEntry {
+    readonly ref: string;
+    readonly label: string;
+    readonly isDefault: boolean;
+    /** False: no recipient name, checkout refuses it (`address_incomplete`). */
+    readonly isComplete: boolean;
+}
+interface OmsAddress {
+    readonly recipientName: string | null;
+    readonly line1: string;
+    readonly line2: string | null;
+    readonly city: string;
+    readonly region: string;
+    readonly postalCode: string;
+    /** Two capital letters. */
+    readonly country: string;
+}
+interface OmsAddressDetail extends OmsAddressEntry {
+    readonly address: OmsAddress;
+}
+interface OmsAddressInput {
+    /** 1 to 60 characters. */
+    readonly label: string;
+    readonly makeDefault?: boolean;
+    readonly address: OmsAddress;
+}
+interface OmsPaymentMethod {
+    /** Stripe's `pm_...`. */
+    readonly paymentMethodId: string;
+    readonly brand: string;
+    readonly last4: string;
+    readonly wallet: 'apple_pay' | 'google_pay' | string | null;
+}
+/** `POST /oms/payment-methods/setup`: a Stripe SetupIntent and its client secret. */
+interface OmsPaymentSetup {
+    readonly setupId: string;
+    /** The SetupIntent client secret. Hand it to Stripe, never log or store it. */
+    readonly payerAction: string;
+}
+/** Stripe's hosted page that saves a card (a Checkout Session in setup mode), for an app with no Stripe SDK. */
+interface OmsCardSetupLink {
+    /** `https://checkout.stripe.com/...`. Open it in an in-app browser; it carries no secret. */
+    readonly url: string;
+}
+/** Everfur's hosted page that runs an order's open 3-D Secure step, for an app with no Stripe SDK. */
+interface OmsCardActionLink {
+    /** The web page with a short-lived ticket in its fragment. Open it once, in an in-app browser; never log it. */
+    readonly url: string;
+    /** When the ticket stops working (ISO 8601), about 15 minutes after it was made. */
+    readonly expiresAt: string;
+}
+type OmsPlanState = 'active' | 'paused' | 'needs_address' | 'cancelled';
+type OmsPlanStopReason = 'customer' | 'consent_revoked' | 'needs_address' | 'payment_declined' | 'needs_prescription' | 'item_unavailable' | 'order_refused';
+interface OmsPlanLine {
+    readonly offerId: string;
+    readonly quantity: number;
+    readonly petId: string | null;
+}
+/** An auto-ship plan (contract 4.15, 8.5). */
+interface OmsPlan {
+    readonly planId: string;
+    readonly lines: readonly OmsPlanLine[];
+    readonly cadenceDays: number;
+    /** An address ref. */
+    readonly destination: string | null;
+    readonly paymentMethodId: string | null;
+    /** 1000 is the 10% subscribe-and-save discount. */
+    readonly discountBps: number;
+    readonly nextRun: string | null;
+    readonly state: OmsPlanState | string;
+    readonly stopReason: OmsPlanStopReason | string | null;
+}
+interface OmsPlanPage {
+    readonly plans: readonly OmsPlan[];
+    readonly nextCursor: string | null;
+}
+interface OmsPlanInput {
+    readonly idempotencyKey: string;
+    /** 7 to 365. */
+    readonly cadenceDays: number;
+    readonly destination: string;
+    readonly paymentMethodId: string;
+    /** Must equal `shop-config.recurringTermsVersion`, else 409 `terms_outdated`. */
+    readonly consentTermsVersion: string;
+    readonly lines: readonly OmsCartLine[];
+}
+interface OmsPlanPatch {
+    readonly idempotencyKey: string;
+    readonly lines?: readonly OmsCartLine[];
+    readonly cadenceDays?: number;
+    readonly destination?: string;
+    readonly paymentMethodId?: string;
+}
+type OmsPlanOperation = 'pause' | 'skip' | 'resume';
+type OmsCycleReviewState = 'open' | 'approving' | 'approved' | 'skipped' | 'withdrawn' | 'failed';
+/** `GET /oms/subscriptions/{plan_id}/cycle`. */
+interface OmsCycleReview {
+    readonly planId: string;
+    /** Null when no review is open: `cycle`, `shipsOn` and `approveBy` then name the next one. */
+    readonly reviewId: string | null;
+    readonly cycle: number;
+    readonly state: OmsCycleReviewState | string | null;
+    readonly lines: readonly OmsPlanLine[];
+    readonly shipsOn: string | null;
+    readonly approveBy: string | null;
+    /** The pre-tax quote of the open review's lines (price and discount per line), when one is open. */
+    readonly quoteLines: readonly OmsQuoteLine[];
+}
+/** `POST /oms/subscriptions/{plan_id}/cycles/{cycle}/draft`: the taxed draft the owner approves. */
+interface OmsCycleDraft {
+    readonly checkoutId: string;
+    readonly shipping: OmsCents;
+    readonly tax: OmsCents;
+    readonly total: OmsCents;
+    readonly expiresAt: string | null;
+}
+
+/** The member's own Cognito id token, asked for on every request. Null (or a throw) means signed out. */
+type OmsGetToken = () => Promise<string | null | undefined> | string | null | undefined;
+interface OmsConsumerAuth {
+    readonly kind: 'everfur_consumer';
+    readonly getToken: OmsGetToken;
+}
+interface OmsClientConfig {
+    /** The API origin, e.g. `https://api.everfur.com`. https only (http is allowed for localhost). */
+    readonly baseUrl: string;
+    /** Default `/api/v1/oms`. */
+    readonly path?: string;
+    readonly auth: OmsConsumerAuth;
+    /** Default `globalThis.fetch`. */
+    readonly fetch?: FetchLike;
+    /** Sent on `POST /checkouts`. Default `web`. */
+    readonly channel?: 'web' | 'app';
+    /** Per-request deadline. Default 30 s. */
+    readonly timeoutMs?: number;
+}
+interface OmsOfferQuery {
+    readonly text?: string;
+    readonly requiresRx?: boolean;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+interface OmsPageQuery {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+interface OmsQuoteRequest {
+    readonly lines: readonly OmsCartLine[];
+    readonly shipTo: string;
+    readonly promoCode?: string;
+}
+interface OmsCheckoutRequest extends OmsQuoteRequest {
+    readonly idempotencyKey: string;
+    readonly receiptEmail?: string;
+}
+interface OmsConfirmRequest {
+    readonly idempotencyKey: string;
+    /** The total the customer saw (the draft's `total`); a mismatch is 409 `price_changed`. */
+    readonly expectedTotal: number;
+    readonly paymentMethodId: string;
+}
+interface OmsReturnRequest {
+    readonly idempotencyKey: string;
+    readonly lines: readonly {
+        readonly lineId: string;
+        readonly quantity: number;
+        readonly reasonCode: string;
+    }[];
+}
+interface OmsCaseRequest {
+    readonly idempotencyKey: string;
+    readonly reasonCode: string;
+    /** At most 4000 characters. */
+    readonly message: string;
+}
+interface OmsCycleApproval {
+    readonly idempotencyKey: string;
+    readonly checkoutId: string;
+    readonly expectedTotal: number;
+}
+interface OmsClient {
+    shopConfig(): Promise<OmsResult<OmsShopConfig>>;
+    offers(query?: OmsOfferQuery): Promise<OmsResult<OmsOfferPage>>;
+    offer(offerId: string): Promise<OmsResult<OmsOffer>>;
+    prescriptions(): Promise<OmsResult<readonly OmsPrescription[]>>;
+    addresses(): Promise<OmsResult<readonly OmsAddressEntry[]>>;
+    address(ref: string): Promise<OmsResult<OmsAddressDetail>>;
+    addAddress(input: OmsAddressInput): Promise<OmsResult<OmsAddressEntry>>;
+    updateAddress(ref: string, input: OmsAddressInput): Promise<OmsResult<OmsAddressEntry>>;
+    removeAddress(ref: string): Promise<OmsResult<void>>;
+    makeDefaultAddress(ref: string): Promise<OmsResult<OmsAddressEntry>>;
+    paymentMethods(): Promise<OmsResult<readonly OmsPaymentMethod[]>>;
+    /** A new SetupIntent each call (5 an hour). Hand `payerAction` to Stripe; never keep it. */
+    setupPaymentMethod(): Promise<OmsResult<OmsPaymentSetup>>;
+    /**
+     * Stripe's hosted card setup page for an app with no Stripe SDK (shares setup's 5 an hour). Stripe sends the member
+     * back to `returnUrl` with `oms_card=done` or `oms_card=canceled`; the backend refuses a URL off its allowlist (400).
+     * The same key inside 24 hours answers the same page.
+     */
+    startCardSetupSession(request: {
+        readonly idempotencyKey: string;
+        readonly returnUrl: string;
+    }): Promise<OmsResult<OmsCardSetupLink>>;
+    removePaymentMethod(paymentMethodId: string): Promise<OmsResult<void>>;
+    quote(request: OmsQuoteRequest): Promise<OmsResult<OmsQuote>>;
+    createCheckout(request: OmsCheckoutRequest): Promise<OmsResult<OmsCheckout>>;
+    confirmCheckout(checkoutId: string, request: OmsConfirmRequest): Promise<OmsResult<OmsConfirmation>>;
+    orders(query?: OmsPageQuery & {
+        readonly reference?: string;
+    }): Promise<OmsResult<OmsOrderPage>>;
+    order(orderId: string): Promise<OmsResult<OmsOrder>>;
+    cancelOrder(orderId: string, request: {
+        readonly idempotencyKey: string;
+        readonly reasonCode: string;
+    }): Promise<OmsResult<OmsCancelOutcome>>;
+    payOrder(orderId: string, request: {
+        readonly idempotencyKey: string;
+        readonly paymentMethodId?: string;
+    }): Promise<OmsResult<OmsPayOutcome>>;
+    /**
+     * The hosted 3-D Secure page for one of the member's orders whose hold needs them, for an app with no Stripe SDK.
+     * The page sends the member back to `returnUrl` with `oms_card_action=succeeded`, `failed` or `canceled`. 409 when
+     * the order has nothing to pay; counts in checkout's rate limit.
+     */
+    cardActionLink(orderId: string, request: {
+        readonly returnUrl: string;
+    }): Promise<OmsResult<OmsCardActionLink>>;
+    requestReturn(orderId: string, request: OmsReturnRequest): Promise<OmsResult<OmsReturn>>;
+    getReturn(returnId: string): Promise<OmsResult<OmsReturn>>;
+    cancelReturn(returnId: string): Promise<OmsResult<OmsReturn>>;
+    openCase(orderId: string, request: OmsCaseRequest): Promise<OmsResult<OmsCase>>;
+    orderCases(orderId: string): Promise<OmsResult<readonly OmsCase[]>>;
+    plans(query?: OmsPageQuery): Promise<OmsResult<OmsPlanPage>>;
+    createPlan(input: OmsPlanInput): Promise<OmsResult<OmsPlan>>;
+    updatePlan(planId: string, patch: OmsPlanPatch): Promise<OmsResult<OmsPlan>>;
+    planAction(planId: string, request: {
+        readonly idempotencyKey: string;
+        readonly operation: OmsPlanOperation;
+    }): Promise<OmsResult<OmsPlan>>;
+    cancelPlan(planId: string): Promise<OmsResult<OmsPlan>>;
+    /** PROVISIONAL (PLAN-APPROVAL-BUILD.md 3.8): not in the contract yet. 404 while the review flag is off. */
+    cycleReview(planId: string): Promise<OmsResult<OmsCycleReview>>;
+    editCycle(planId: string, cycle: number, request: {
+        readonly idempotencyKey: string;
+        readonly lines: readonly OmsCartLine[];
+    }): Promise<OmsResult<OmsCycleReview>>;
+    draftCycle(planId: string, cycle: number): Promise<OmsResult<OmsCycleDraft>>;
+    approveCycle(planId: string, cycle: number, request: OmsCycleApproval): Promise<OmsResult<OmsConfirmation>>;
+    skipCycle(planId: string, cycle: number, request: {
+        readonly idempotencyKey: string;
+    }): Promise<OmsResult<OmsPlan>>;
+}
+declare function createOmsClient(config: OmsClientConfig): OmsClient;
+
+type ShopPaymentStepResult = {
+    readonly ok: true;
+}
+/**
+ * The step did not finish. `message` is Stripe's own line, shown as is. `closed` is true when the customer left the
+ * step themselves (closed the in-app browser or cancelled the hosted page): not a failure, nothing was refused, and
+ * the shop says so with its own line (`cardStepClosed`) instead of `cardStepFailed`.
+ */
+ | {
+    readonly ok: false;
+    readonly message: string | null;
+    readonly closed?: boolean;
+};
+/** What the shop knows about the step it hands over: the order whose hold needs the customer. */
+interface ShopPayerActionContext {
+    readonly orderId: string;
+}
+interface ShopPaymentsPort {
+    /** Finish a SetupIntent (save a card). The card then shows in `GET /payment-methods`. */
+    confirmCardSetup(clientSecret: string): Promise<ShopPaymentStepResult>;
+    /**
+     * Run a PaymentIntent's next action (3-D Secure). The shop confirms again with a new key afterwards. `context` names
+     * the order, for a port that runs the step on a hosted page (React Native's `createInAppBrowserCard`) and so never
+     * uses the client secret.
+     */
+    handleNextAction(clientSecret: string, context?: ShopPayerActionContext): Promise<ShopPaymentStepResult>;
+}
+/** The two Stripe.js calls the shop uses, as Stripe.js declares them (structural; no Stripe import). */
+interface StripeJsLike {
+    handleNextAction(options: {
+        clientSecret: string;
+    }): Promise<{
+        error?: {
+            message?: string;
+        };
+    }>;
+    confirmSetup(options: {
+        clientSecret: string;
+        elements?: unknown;
+        confirmParams?: Record<string, unknown>;
+        redirect?: 'if_required' | 'always';
+    }): Promise<{
+        error?: {
+            message?: string;
+        };
+    }>;
+}
+interface StripeJsPaymentsOptions {
+    /** The Payment Element instance the host mounted for card entry (`stripe.elements({clientSecret})`). */
+    readonly elementsFor?: (clientSecret: string) => unknown;
+    /** Where Stripe returns after a redirect-based method. Https only. */
+    readonly returnUrl?: string;
+}
+/** A `ShopPaymentsPort` over a Stripe.js instance the host loaded with the shop's publishable key. */
+declare function createStripeJsPayments(stripe: StripeJsLike, options?: StripeJsPaymentsOptions): ShopPaymentsPort;
+
+/** Keys for one user action. `key(step)` is stable until `next(step)`. */
+declare class ShopActionKeys {
+    private readonly make;
+    private readonly keys;
+    constructor(make?: () => string);
+    key(step: string): string;
+    /** A fresh key for this step (after 3-D Secure, or after a refusal the customer fixed). */
+    next(step: string): string;
+}
+type ShopConfirmOutcome = {
+    readonly kind: 'confirmed';
+    readonly orderIds: readonly string[];
+}
+/** The bank wants 3-D Secure and the host gave no payments port; the order can be paid later from its page. */
+ | {
+    readonly kind: 'needsPayerAction';
+    readonly orderIds: readonly string[];
+}
+/** The step failed (the bank refused it, or it could not run). Stripe's own line when it gave one. */
+ | {
+    readonly kind: 'payerActionFailed';
+    readonly orderIds: readonly string[];
+    readonly message: string | null;
+}
+/** The customer closed the step themselves. Nothing was refused; the order can be paid later from its page. */
+ | {
+    readonly kind: 'payerActionClosed';
+    readonly orderIds: readonly string[];
+} | {
+    readonly kind: 'failed';
+    readonly error: OmsError;
+};
+
+interface ShopPackageLine {
+    readonly offerId: string;
+    readonly quantity: number;
+    readonly petId: string | null;
+    /** Null when the offer could not be read (no longer sold): the row shows as out of stock. */
+    readonly offer: OmsOffer | null;
+}
+interface ShopPackage {
+    readonly plan: OmsPlan;
+    readonly review: OmsCycleReview;
+    readonly lines: readonly ShopPackageLine[];
+    /** The taxed draft the owner approves; null when no review is open or the draft was refused. */
+    readonly draft: OmsCycleDraft | null;
+}
+interface ShopPackageSource {
+    /** The household's package this month; `ok(null)` when there is no plan yet (first run, not designed). */
+    load(): Promise<OmsResult<ShopPackage | null>>;
+    /** Take one line out of this month's package only. */
+    removeLine(pkg: ShopPackage, index: number, keys: ShopActionKeys): Promise<OmsResult<ShopPackage | null>>;
+    skip(pkg: ShopPackage, keys: ShopActionKeys): Promise<OmsResult<void>>;
+    approve(pkg: ShopPackage, keys: ShopActionKeys, payments: ShopPaymentsPort | null): Promise<ShopConfirmOutcome>;
+}
+/** The stub: no package, ever. The Package tab stays hidden. */
+declare const UNAVAILABLE_PACKAGE_SOURCE: ShopPackageSource;
+/** The package over the OMS plan review routes (PROVISIONAL, see the header). */
+declare function createOmsPackageSource(client: OmsClient): ShopPackageSource;
+
+declare const SHOP_COPY: {
+    tabsLabel: string;
+    tabPackage: string;
+    tabShop: string;
+    tabOrders: string;
+    tabPlan: string;
+    /** careShop.ts CARE_LEGAL: the packet's legal line without "Sample products and prices." (HANDOFF). */
+    legal: string;
+    /** care-tracking.html legal line, without "Sample products and prices." */
+    legalTracking: string;
+    loadFailed: (thing: string) => string;
+    tryAgain: string;
+    actionFailed: string;
+    saving: string;
+    keepIt: string;
+    /** pet-pack.html sheet close button. */
+    close: string;
+    thingPackage: string;
+    thingShop: string;
+    thingProduct: string;
+    thingPlan: string;
+    /** WebOrdersPage.tsx: "We couldn’t load your orders." */
+    thingOrders: string;
+    /** WebOrderPage.tsx: "We couldn’t load this order." */
+    thingOrder: string;
+    packageTitle: (month: string) => string;
+    packageSub: (names: readonly string[], reviewBy: string | null, arrives: string | null) => string | null;
+    inThisPackage: string;
+    reviewBy: (day: string) => string;
+    forPet: (name: string) => string;
+    details: string;
+    remove: string;
+    removed: string;
+    total: string;
+    items: string;
+    shipping: string;
+    tax: string;
+    free: string;
+    approveAndShip: string;
+    /** Raph's phone Care (care, card head pill): "4 items". No phone line for one item yet. */
+    itemCount: (n: number) => string;
+    /** Raph's phone Care tray bar: "Approve and ship · $138.26". */
+    withTotal: (label: string, total: string) => string;
+    /** care.html aside aria-label. */
+    approveRegion: string;
+    /** care-tracking.html / care-plan.html / care-product.html aside aria-labels. */
+    packageDetailsRegion: string;
+    deliveryPaymentRegion: string;
+    questionsRegion: string;
+    approving: string;
+    skipThisMonth: string;
+    /** careShop.ts chargedLine. Raph's line; see the report: the card is HELD at approval, captured after acceptance. */
+    chargedWhenShips: (card: string) => string;
+    rxCheckedFirst: string;
+    delivery: string;
+    arrives: (day: string) => string;
+    change: string;
+    outOfStock: string;
+    /** careShop.ts PACKAGE_OUT_OF_STOCK. */
+    packageOutOfStock: string;
+    /** careShop.ts packageEmptyLine. */
+    packageEmpty: (month: string) => string;
+    /** A line whose offer is no longer sold: no packet line names it. */
+    itemNoLongerSold: string;
+    /** PLAN-APPROVAL-BUILD 8: review closed, approval in progress, draft expired, price changed. */
+    reviewClosed: string;
+    approvalInProgress: string;
+    priceChanged: string;
+    cardStepFailed: string;
+    /** The member closed the card step (the in-app browser or the hosted page) without finishing: no line names it. */
+    cardStepClosed: string;
+    noCardOnFile: string;
+    shopTitle: string;
+    searchLabel: string;
+    searchPlaceholder: string;
+    filtersLabel: string;
+    filterAll: string;
+    refillSoon: string;
+    inMonthsPackage: (month: string) => string;
+    forPets: (names: readonly string[]) => string;
+    /** A shelf with no pet names to put in "For Evie and Toast". */
+    allProducts: string;
+    rx: string;
+    /** careShop.ts tileMeta. */
+    hasPrescription: (name: string) => string;
+    needsPrescription: string;
+    noMatches: (q: string) => string;
+    nothingHereYet: string;
+    photoToCome: string;
+    backToShop: string;
+    howOften: string;
+    /** careShop.ts everyMonthTitle. */
+    everyMonthIn: (name: string) => string;
+    skipOrStop: string;
+    justOnce: string;
+    shipsWith: (month: string) => string;
+    /** "Just once" is a buy-now checkout on the OMS, not a line in the package: no packet line says so. */
+    justOnceShipsNow: string;
+    oneFewer: string;
+    oneMore: string;
+    quantity: string;
+    /** careShop.ts addLabel. */
+    addToPackage: (month: string) => string;
+    refillInPackage: (month: string) => string;
+    /** The buy-now and the start-a-plan buttons: no packet line. */
+    buyNow: string;
+    startPlan: string;
+    adding: string;
+    outOfStockNow: string;
+    prescription: string;
+    noPrescriptionFor: (name: string) => string;
+    bookVideoVisit: string;
+    refillsLeft: (n: number) => string;
+    /** Contract 2.1, `rx_being_prepared`. */
+    rxBeingPrepared: string;
+    /** Contract 5.3 `too_soon` / `refills_used` / `expired`: meanings, no lines yet. */
+    rxTooSoon: string;
+    rxRenew: string;
+    rxPick: string;
+    educational: string;
+    planTitle: string;
+    whatRepeats: string;
+    repeatsLabel: (title: string) => string;
+    /** careShop.ts cadence. */
+    cadenceMonths: (months: number) => string;
+    cadenceDays: string;
+    /** careShop.ts REPEATS_EMPTY. */
+    repeatsEmpty: string;
+    nextPackage: string;
+    reviewByLabel: string;
+    ships: string;
+    reviewMonthsPackage: (month: string) => string;
+    deliveryAndPayment: string;
+    shipTo: string;
+    payWith: string;
+    needABreak: string;
+    skipMonth: (month: string) => string;
+    skipMonthAsk: (month: string) => string;
+    skipMonthBody: string;
+    pausePlan: string;
+    pausePlanAsk: string;
+    pausePlanBody: string;
+    /** careShop.ts declinedLine. */
+    declined: (month: string | null) => string;
+    resumePlan: string;
+    /** Contract 8.5 stop reasons other than payment_declined: no lines yet. */
+    stopReason: (reason: string) => string;
+    consentTitle: string;
+    consentBody: string;
+    consentTermsLink: string;
+    consentAgree: string;
+    ordersTitle: string;
+    ordersSub: (names: readonly string[]) => string;
+    allOrders: string;
+    /** careOrders.ts orderRow. */
+    placed: (day: string) => string;
+    /** HANDOFF care-orders Empty. */
+    ordersEmpty: string;
+    paymentFailed: string;
+    backToCare: string;
+    onItsWay: (title: string) => string;
+    shouldArrive: (day: string) => string;
+    whereItStands: string;
+    stepApproved: string;
+    stepChecking: string;
+    stepFilled: string;
+    stepShipped: string;
+    stepDelivered: string;
+    now: string;
+    expected: (day: string) => string;
+    inTheBox: string;
+    payment: string;
+    cancelOrder: string;
+    payOrder: string;
+    trackPackage: string;
+    /** Contract 5.1 "Show as". */
+    orderStatus: Readonly<Record<string, string>>;
+    addressTitle: string;
+    addressLabel: string;
+    addressRecipient: string;
+    addressLine1: string;
+    addressLine2: string;
+    addressCity: string;
+    addressRegion: string;
+    addressPostal: string;
+    addressSave: string;
+    addressNeeded: string;
+    cardTitle: string;
+    cardBody: string;
+    cardStart: string;
+    cardUnavailable: string;
+    confirmTitle: string;
+    confirmPay: string;
+    /** Contract 2.1 "Show" lines. */
+    refusal: Readonly<Record<string, string>>;
+    rateLimited: string;
+};
+type ShopCopy = typeof SHOP_COPY;
+/** The placeholder keys in `SHOP_COPY`, for the report and for a host filling them in. */
+declare const SHOP_COPY_PLACEHOLDERS: readonly string[];
+/** The host's words over the defaults. */
+declare function shopCopy(overrides?: Partial<ShopCopy>): ShopCopy;
+
+interface ShopPet {
+    readonly petId: string;
+    readonly name: string;
+}
+
+type ShopRoute = {
+    readonly name: 'package';
+} | {
+    readonly name: 'shop';
+    readonly query?: string;
+} | {
+    readonly name: 'product';
+    readonly offerId: string;
+    readonly petId?: string;
+} | {
+    readonly name: 'plan';
+} | {
+    readonly name: 'orders';
+} | {
+    readonly name: 'order';
+    readonly orderId: string;
+} | {
+    readonly name: 'address';
+    readonly then?: ShopRoute;
+} | {
+    readonly name: 'card';
+    readonly then?: ShopRoute;
+} | {
+    readonly name: 'buy';
+    readonly offerId: string;
+    readonly quantity: number;
+    readonly petId?: string;
+    readonly rxId?: string;
+} | {
+    readonly name: 'consent';
+    readonly offerId: string;
+    readonly quantity: number;
+    readonly petId?: string;
+    readonly rxId?: string;
+};
+type ShopTabName = 'package' | 'shop' | 'orders' | 'plan';
+
+/**
+ * How a card step that left the page came back, for a host whose card steps are full-page redirects (the web): the
+ * host reads its return URL and hands the outcome to the shop once. `card` is saving a card (shown on the card page),
+ * `cardAction` an order's 3-D Secure step (shown on that order's page). `done` shows no line: the page reads the
+ * saved cards or the order again.
+ */
+interface ShopCardReturn {
+    readonly step: 'card' | 'cardAction';
+    readonly outcome: 'done' | 'closed' | 'failed';
+}
+/**
+ * A card saved outside the shop's own Stripe step: React Native opens a hosted page in an in-app browser and reports
+ * how it ended (`closed` when the member left it themselves). The shop then reads the saved cards again; no card data
+ * or secret passes through the shop. On the web it sends the page to the hosted setup page and need not resolve; the
+ * outcome comes back through the host's URL as `cardReturn`.
+ */
+type ShopCardHandoff = () => Promise<ShopPaymentStepResult>;
+
+declare function newIdempotencyKey(): string;
+
+export { isOmsUnavailable as A, newIdempotencyKey as B, shopCopy as C, type OmsCardActionLink as D, type OmsCardSetupLink as E, type ShopPayerActionContext as F, type OmsClient as O, type ShopPet as S, UNAVAILABLE_PACKAGE_SOURCE as U, type ShopPaymentsPort as a, type ShopPackageSource as b, type ShopCopy as c, type ShopRoute as d, type ShopCardHandoff as e, type ShopCardReturn as f, type OmsCartLine as g, type OmsClientConfig as h, type OmsConsumerAuth as i, type OmsError as j, type OmsGetToken as k, type OmsPlanOperation as l, type OmsResult as m, SHOP_COPY as n, SHOP_COPY_PLACEHOLDERS as o, type ShopPackage as p, type ShopPackageLine as q, type ShopPaymentStepResult as r, type ShopTabName as s, type StripeJsLike as t, type StripeJsPaymentsOptions as u, createOmsClient as v, createOmsPackageSource as w, createStripeJsPayments as x, isOmsRefusal as y, isOmsRetryable as z };