@isnap/sdk 2.2.0-next.227 → 2.2.0-next.228

package/dist/generated/openapi.d.ts

@@ -2972,7 +2972,7 @@ export interface paths {
             parameters: {
                 query?: {
                     /** @description Keep the pre-orders in this status. */
-                    status?: "draft" | "provisioning" | "fulfilled" | "cancelled";
+                    status?: "draft" | "awaiting_payment" | "provisioning" | "fulfilled" | "cancelled";
                     /** @description The `next_cursor` of the previous page. Omit it for the first page. An unreadable cursor restarts from the first page, without an error. */
                     cursor?: string;
                     /** @description Number of pre-orders per page, from 1 to 100. Default: 25. */
@@ -3036,7 +3036,7 @@ export interface paths {
          * Create a pre-order
          * @description Creates a draft pre-order for one rented iMessage line. Accepts an API key. A line-scoped key is not limited to its list on this operation. A draft has no effect: it creates no line, takes no payment, and never expires. Call `POST /v1/pre-orders/{id}/confirm` to commit it. There is no limit on the number of drafts. `Idempotency-Key` is ignored: a repeated call creates another draft. Creating a draft sends no event.
          *
-         *     `preferred_area_codes` lists up to 5 area codes in order of preference, and `inbound_only` chooses between an inbound-only line and a two-way line. `billing_tier`, when sent, must be `rental_iphone`: `rental_android` returns `400 android_rental_not_purchasable`, and the four other values return `400 tier_not_pre_orderable`. `billing_anchor_at` is stored on the pre-order and carried onto the line at confirmation: a value more than 31 days after the call returns `400 billing_anchor_too_far`, and the confirmation does not check it again. A key that is not listed, `quantity` included, returns `400 validation_failed`: one pre-order is one line.
+         *     `preferred_area_codes` lists up to 5 area codes in order of preference, and `inbound_only` chooses between an inbound-only line and a two-way line. `billing_tier`, when sent, must be `rental_iphone`: `rental_android` returns `400 android_rental_not_purchasable`, and the four other values return `400 tier_not_pre_orderable`. `billing_anchor_at` is stored on the pre-order and carried onto the line when the line is created: a value more than 31 days after the call returns `400 billing_anchor_too_far`, and it is not checked again. A key that is not listed, `quantity` included, returns `400 validation_failed`: one pre-order is one line.
          */
         post: {
             parameters: {
@@ -3162,11 +3162,17 @@ export interface paths {
         put?: never;
         /**
          * Confirm a pre-order
-         * @description Commits a draft pre-order. Accepts an API key. A line-scoped key is not limited to its list on this operation: it can confirm any draft of the account. The call sets `status` to `provisioning` and `estimated_fulfillment` to the time of the call plus 72 hours, and creates on your account a rented iMessage line with `status: provisioning`, with the `inbound_only` and the `billing_anchor_at` of the pre-order. When a number in one of your area codes is in stock, it is assigned to the line immediately. The confirmation sends no event: iSnap sends `pre_order.fulfilled`, which carries the `line_id`, when the line is handed over.
+         * @description Commits a draft pre-order. Accepts an API key. A line-scoped key is not limited to its list on this operation: it can confirm any draft of the account. The confirmation sends no event: iSnap sends `pre_order.fulfilled`, which carries the `line_id`, when the line is handed over.
          *
-         *     A wholesale partner pays nothing at confirmation: `stripe_client_secret` is `null`, and the line is billed on the monthly invoice from the day it is handed over. For a direct account, confirm starts a monthly subscription and returns `stripe_client_secret`, a client secret that your payment page passes to the payment form of Stripe to collect the first month. The line is created whether or not that payment completes. The secret is returned in this response only and confirm cannot be repeated: store the secret before anything else.
+         *     The build of a pre-order sets `status` to `provisioning` and `estimated_fulfillment` to the time the build starts plus 72 hours, and creates on your account a rented iMessage line with `status: provisioning`, with the `inbound_only` and the `billing_anchor_at` of the pre-order. When a number is in stock in one of your area codes, in their order of preference, it is assigned to the line when the build starts. A pre-order with no `preferred_area_codes` takes any number in stock.
          *
-         *     Only a draft can be confirmed: any other pre-order returns `400 pre_order_not_draft`, and a confirmation that runs at the same time as another confirmation or as a cancellation returns `409 pre_order_not_draft`. A confirmed pre-order cannot be canceled through the API.
+         *     For a wholesale partner the build starts with the confirmation. A wholesale partner pays nothing at confirmation: `stripe_client_secret` is `null`, and the line is billed on the monthly invoice from the day it is handed over.
+         *
+         *     For a direct account the build starts when the first month is paid. Confirm starts a monthly subscription, sets `status` to `awaiting_payment` and returns `stripe_client_secret`, a client secret that your payment page passes to the payment form of Stripe to collect the first month. Only card payments are accepted. Until that payment succeeds, no line is created and `estimated_fulfillment` is `null`. After paying, read the pre-order with `GET /v1/pre-orders/{id}` until `status` is `provisioning`. When the first month is not paid within 23 hours of the confirmation, `status` becomes `cancelled` and iSnap sends `pre_order.cancelled`. When a credit balance of the account at Stripe covers the first month, there is nothing to pay: the build starts with the confirmation and `stripe_client_secret` is `null`. The first month starts at the confirmation, not when the line is handed over, and the next invoice is issued one month after the confirmation. The hand-over of the line takes no payment and does not change when the subscription is invoiced.
+         *
+         *     Confirm can be repeated while `status` is `awaiting_payment`: it returns the same client secret and starts no second subscription. Repeated after the payment succeeded, it returns the pre-order in `provisioning`.
+         *
+         *     Any other pre-order returns `400 pre_order_not_draft`, including one that was canceled because its first month was not paid in time. A confirmation that runs at the same time as a cancellation, or for a wholesale partner as another confirmation, returns `409 pre_order_not_draft`. When Stripe cannot be reached, the call returns `503 payment_provider_unavailable`: nothing changed, and the call can be repeated. When Stripe refuses the request for the account, the call returns `409 payment_setup_failed`: nothing changed, and repeating the call does not help. Once its build has started, a pre-order cannot be canceled through the API.
          */
         post: {
             parameters: {
@@ -3180,7 +3186,7 @@ export interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description The pre-order, in status `provisioning`. */
+                /** @description The pre-order: in status `awaiting_payment` with its `stripe_client_secret` for a direct account whose first month is due, in status `provisioning` otherwise. */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -3200,7 +3206,7 @@ export interface paths {
                         };
                     };
                 };
-                /** @description Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. It is `pre_order_not_draft` when the pre-order is not a draft. */
+                /** @description Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. It is `pre_order_not_draft` when the pre-order is neither a draft nor in `awaiting_payment`, except a pre-order in `provisioning` whose first month was paid, which a repeated confirm returns. */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -3227,6 +3233,15 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorEnvelope"];
                     };
                 };
+                /** @description Conflict. `error.code` is `pre_order_not_draft` when a cancellation, or for a wholesale partner another confirmation, ran at the same time and won. It is `payment_setup_failed` when Stripe refused the request for the account: repeating the call does not help. */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
                 /** @description Too many requests. `error.code` is `rate_limit_exceeded` when more than 100 requests came from the same network address in 60 seconds, whatever their API key or account: wait `error.retry_after` seconds. */
                 429: {
                     headers: {
@@ -3245,6 +3260,15 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorEnvelope"];
                     };
                 };
+                /** @description Service unavailable. `error.code` is `payment_provider_unavailable`: Stripe could not be reached. Nothing changed, and the call can be repeated. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
             };
         };
         delete?: never;
@@ -3262,7 +3286,7 @@ export interface paths {
         };
         /**
          * Get a pre-order
-         * @description Returns one pre-order of the account. Accepts an API key. A line-scoped key is not limited to its list on this operation. A pre-order carries no line id: the line it produces is announced by `pre_order.fulfilled`, which carries the `line_id`. `stripe_client_secret` is `null` here. A pre-order of another account, or an unknown id, returns `404 not_found`.
+         * @description Returns one pre-order of the account. Accepts an API key. A line-scoped key is not limited to its list on this operation. A pre-order carries no line id: the line it produces is announced by `pre_order.fulfilled`, which carries the `line_id`. `stripe_client_secret` is `null` here. Reading a pre-order in status `awaiting_payment` checks its first-month payment with Stripe: when that payment has succeeded, the build starts and the pre-order is returned in `provisioning`. When Stripe cannot be reached, the read still answers, with the pre-order in `awaiting_payment`. A pre-order of another account, or an unknown id, returns `404 not_found`.
          */
         get: {
             parameters: {
@@ -3448,7 +3472,7 @@ export interface paths {
         put?: never;
         /**
          * Cancel a pre-order
-         * @description Cancels a draft pre-order: nothing was created and nothing was charged. Accepts an API key. A line-scoped key is not limited to its list on this operation. Sets `status` to `cancelled` and sends `pre_order.cancelled`. Only a draft can be canceled: a pre-order that is confirmed, fulfilled or already canceled returns `400 pre_order_already_confirmed`, and a cancellation that runs at the same time as a confirmation or as another cancellation returns `409 pre_order_already_confirmed`. A confirmed pre-order cannot be canceled through the API.
+         * @description Cancels a pre-order in status `draft` or `awaiting_payment`: nothing was created and nothing was charged. Accepts an API key. A line-scoped key is not limited to its list on this operation. Sets `status` to `cancelled` and sends `pre_order.cancelled`. For a pre-order in `awaiting_payment`, the first-month payment is canceled first: the client secret returned by confirm can no longer be used. When that first month is already paid, the call returns `409 pre_order_already_paid` and the build goes on. A pre-order that is `provisioning`, `fulfilled` or already `cancelled` returns `400 pre_order_already_confirmed`, and the cancellation of a draft that runs at the same time as another cancellation, or as the confirmation of a wholesale partner, returns `409 pre_order_already_confirmed`. When Stripe cannot be reached, the call returns `503 payment_provider_unavailable`: nothing changed, and the call can be repeated. When Stripe refuses the request for the account, the call returns `409 payment_setup_failed`: nothing changed, and repeating the call does not help. Once its build has started, a pre-order cannot be canceled through the API.
          */
         post: {
             parameters: {
@@ -3482,7 +3506,7 @@ export interface paths {
                         };
                     };
                 };
-                /** @description Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. It is `pre_order_already_confirmed` when the pre-order is not a draft: it is confirmed, fulfilled or already canceled. */
+                /** @description Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. It is `pre_order_already_confirmed` when the pre-order is `provisioning`, `fulfilled` or already `cancelled`. */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -3509,7 +3533,7 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorEnvelope"];
                     };
                 };
-                /** @description Conflict. `error.code` is `pre_order_already_confirmed`: a confirmation or another cancellation of the same pre-order ran at the same time and won. */
+                /** @description Conflict. `error.code` is `pre_order_already_paid` when the first month is already paid. It is `pre_order_already_confirmed` when a confirmation or another cancellation of the same draft ran at the same time and won. It is `payment_setup_failed` when Stripe refused the request for the account: repeating the call does not help. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -3536,6 +3560,15 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorEnvelope"];
                     };
                 };
+                /** @description Service unavailable. `error.code` is `payment_provider_unavailable`: Stripe could not be reached. Nothing changed, and the call can be repeated. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
             };
         };
         delete?: never;
@@ -9147,12 +9180,12 @@ export interface components {
             preferred_area_codes: string[];
             /** @description `true` for an inbound-only line, `false` for a two-way line. */
             inbound_only: boolean;
-            /** @description The billing anchor you set when creating the pre-order, carried onto the line at confirmation. `null` when you set none. */
+            /** @description The billing anchor you set when creating the pre-order, carried onto the line when the line is created. `null` when you set none. */
             billing_anchor_at: string | null;
             status: components["schemas"]["PreOrderStatus"];
-            /** @description Client secret for the payment form of Stripe, to collect the first month. Set only in the response of `POST /v1/pre-orders/{id}/confirm`, for an account that is not a wholesale partner. `null` in every other response. */
+            /** @description Client secret for the payment form of Stripe, to collect the first month. Set only in the response of `POST /v1/pre-orders/{id}/confirm`, when that response carries the pre-order in status `awaiting_payment`: the first time and every time confirm is repeated. `null` in every other response. */
             stripe_client_secret: string | null;
-            /** @description Estimated time of the hand-over of the line: the time of the confirmation plus 72 hours. Set once at confirmation and never revised. `null` until the pre-order is confirmed. */
+            /** @description Estimated time of the hand-over of the line: the time the build starts plus 72 hours. Set once, when the build starts, and never revised. `null` while the pre-order is `draft` or `awaiting_payment`, and on a pre-order canceled before its build started. */
             estimated_fulfillment: string | null;
             device_status?: components["schemas"]["DeviceFulfillmentStatus"];
             /** @description Timestamp of creation, ISO 8601 in UTC. */
@@ -9170,12 +9203,12 @@ export interface components {
             } | null;
         };
         /**
-         * @description `draft`: created, with no effect. `provisioning`: confirmed, and the line is being prepared. `fulfilled`: the line is handed over. `cancelled`: the draft was canceled. A confirmed pre-order never becomes `cancelled`.
+         * @description `draft`: created, with no effect. `awaiting_payment`: confirmed by a direct account, and the first month is due; nothing is built until it is paid. `provisioning`: the build has started, and the line is being prepared. `fulfilled`: the line is handed over. `cancelled`: the pre-order ended with no line. You canceled it, its first month was not paid within 23 hours of the confirmation, or its subscription was canceled before the first payment. A pre-order whose build has started never becomes `cancelled`.
          * @enum {string}
          */
-        PreOrderStatus: "draft" | "provisioning" | "fulfilled" | "cancelled";
+        PreOrderStatus: "draft" | "awaiting_payment" | "provisioning" | "fulfilled" | "cancelled";
         /**
-         * @description Progress of the line. `awaiting_hardware`: the line is not ready; also the value of a draft and of a canceled draft. `ready`: the line is prepared. `deployed`: the line is handed over. `received` and `setup_in_progress` are declared and never returned. Always present on a pre-order, and never `null`.
+         * @description Progress of the line. `awaiting_hardware`: the line is not ready; also the value of a pre-order that has no line: a draft, a pre-order in `awaiting_payment`, a canceled pre-order. `ready`: the line is prepared. `deployed`: the line is handed over. `received` and `setup_in_progress` are declared and never returned. Always present on a pre-order, and never `null`.
          * @enum {string|null}
          */
         DeviceFulfillmentStatus: "awaiting_hardware" | "received" | "setup_in_progress" | "ready" | "deployed" | null;

package/dist/resources/preorders.d.ts

@@ -28,14 +28,34 @@ export declare class PreOrdersResource extends BaseResource {
     create(body: CreatePreOrderBody, opts?: RequestOptions): Promise<PreOrder>;
     /**
      * `POST /v1/pre-orders/{id}/confirm` — confirm a `draft` pre-order. The
-     * binding step: engages the one-month commitment (full month, no proration)
-     * and triggers procurement (mints the provisioning line + fulfillment task,
-     * notifies ops). Returns the pre-order in `provisioning`; ops procures the
-     * hardware and the partner is notified via the `pre_order.fulfilled` webhook
-     * when a matching line is ready. Direct customers get a Stripe
-     * `stripe_client_secret` to confirm the first-month charge; wholesale
-     * partners are billed EOM (no per-line Stripe sub). Only a draft can be
-     * confirmed.
+     * binding step: engages the one-month commitment (full month, no proration).
+     *
+     * A wholesale partner (billed at the end of the month) gets the pre-order
+     * back in `provisioning`: the line is being built, and the
+     * `pre_order.fulfilled` webhook fires when it is live.
+     *
+     * A direct account gets it back in `awaiting_payment` with
+     * `stripe_client_secret`, the client secret of the first-month payment, to
+     * confirm with the Stripe Payment Element (card only). Nothing is built until
+     * that payment succeeds; the pre-order then moves to `provisioning`: read it
+     * with `get()` until it leaves `awaiting_payment`. Calling `confirm()` again
+     * while it is `awaiting_payment` returns the same secret. When the first
+     * month is already paid (the account's credit balance covers it, or
+     * `confirm()` is repeated after the payment), the pre-order comes back in
+     * `provisioning` with `stripe_client_secret: null`.
+     *
+     * The first month starts at the confirmation, not when the line is handed
+     * over, and the next invoice is issued one month after the confirmation. The
+     * hand-over of the line takes no payment and does not change when the
+     * subscription is invoiced.
+     *
+     * An unpaid first month cancels the pre-order 23 hours after the
+     * confirmation; `confirm()` on it then throws a `BadRequestError` (400
+     * `pre_order_not_draft`), like any confirm of a pre-order that is not a
+     * draft. A 503 `payment_provider_unavailable` means nothing changed and the
+     * call can be repeated (the SDK retries it). A `ConflictError` with 409
+     * `payment_setup_failed` means the payment provider refused the request for
+     * the account: it is not retried, and repeating it does not help.
      */
     confirm(id: string, opts?: RequestOptions): Promise<PreOrder>;
     /**
@@ -51,7 +71,12 @@ export declare class PreOrdersResource extends BaseResource {
      * `has_more` is false.
      */
     list(query?: ListPreOrdersQuery, opts?: RequestOptions): Promise<PreOrderListData>;
-    /** `GET /v1/pre-orders/{id}` — fetch a single pre-order by id. */
+    /**
+     * `GET /v1/pre-orders/{id}` — fetch a single pre-order by id. Reading a
+     * pre-order that is `awaiting_payment` checks its first-month payment: once
+     * it has succeeded, the pre-order comes back in `provisioning`.
+     * `stripe_client_secret` is always `null` here.
+     */
     get(id: string, opts?: RequestOptions): Promise<PreOrder>;
     /**
      * `PATCH /v1/pre-orders/{id}` — merge `metadata` into the pre-order's tags.
@@ -64,9 +89,13 @@ export declare class PreOrdersResource extends BaseResource {
      */
     update(id: string, body: PatchPreOrderBody, opts?: RequestOptions): Promise<PreOrder>;
     /**
-     * `POST /v1/pre-orders/{id}/cancel` — cancel a pre-order before it is
-     * fulfilled. Refunds the Stripe payment intent (if charged) and releases the
-     * procurement task. No-op on an already-cancelled / fulfilled pre-order.
+     * `POST /v1/pre-orders/{id}/cancel` — cancel a `draft` or `awaiting_payment`
+     * pre-order. Free: nothing is charged or built in either status. For an
+     * `awaiting_payment` pre-order the first-month payment is voided first, so
+     * its client secret can no longer charge; a first month already paid throws
+     * a `ConflictError` (409 `pre_order_already_paid`). A pre-order that is
+     * `provisioning`, `fulfilled` or already `cancelled` is refused (400
+     * `pre_order_already_confirmed`).
      */
     cancel(id: string, opts?: RequestOptions): Promise<PreOrder>;
 }

package/dist/resources/preorders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preorders.d.ts","sourceRoot":"","sources":["../../src/resources/preorders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAA;AACxD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAA;AAIpE,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5E,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAC1C,KAAK,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAC/C,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAA;AAChC,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;AACnG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAA;AAEtE,qBAAa,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS7D;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,KAAK,GAAE,kBAAuB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOtF,kEAAkE;IAClE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IASzD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IASrF;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;CAQ7D"}
+{"version":3,"file":"preorders.d.ts","sourceRoot":"","sources":["../../src/resources/preorders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAA;AACxD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAA;AAIpE,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5E,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAC1C,KAAK,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAC/C,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAA;AAChC,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;AACnG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAA;AAEtE,qBAAa,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS7D;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,KAAK,GAAE,kBAAuB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOtF;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IASzD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IASrF;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;CAQ7D"}

package/dist/resources/preorders.js

@@ -22,14 +22,34 @@ export class PreOrdersResource extends BaseResource {
     }
     /**
      * `POST /v1/pre-orders/{id}/confirm` — confirm a `draft` pre-order. The
-     * binding step: engages the one-month commitment (full month, no proration)
-     * and triggers procurement (mints the provisioning line + fulfillment task,
-     * notifies ops). Returns the pre-order in `provisioning`; ops procures the
-     * hardware and the partner is notified via the `pre_order.fulfilled` webhook
-     * when a matching line is ready. Direct customers get a Stripe
-     * `stripe_client_secret` to confirm the first-month charge; wholesale
-     * partners are billed EOM (no per-line Stripe sub). Only a draft can be
-     * confirmed.
+     * binding step: engages the one-month commitment (full month, no proration).
+     *
+     * A wholesale partner (billed at the end of the month) gets the pre-order
+     * back in `provisioning`: the line is being built, and the
+     * `pre_order.fulfilled` webhook fires when it is live.
+     *
+     * A direct account gets it back in `awaiting_payment` with
+     * `stripe_client_secret`, the client secret of the first-month payment, to
+     * confirm with the Stripe Payment Element (card only). Nothing is built until
+     * that payment succeeds; the pre-order then moves to `provisioning`: read it
+     * with `get()` until it leaves `awaiting_payment`. Calling `confirm()` again
+     * while it is `awaiting_payment` returns the same secret. When the first
+     * month is already paid (the account's credit balance covers it, or
+     * `confirm()` is repeated after the payment), the pre-order comes back in
+     * `provisioning` with `stripe_client_secret: null`.
+     *
+     * The first month starts at the confirmation, not when the line is handed
+     * over, and the next invoice is issued one month after the confirmation. The
+     * hand-over of the line takes no payment and does not change when the
+     * subscription is invoiced.
+     *
+     * An unpaid first month cancels the pre-order 23 hours after the
+     * confirmation; `confirm()` on it then throws a `BadRequestError` (400
+     * `pre_order_not_draft`), like any confirm of a pre-order that is not a
+     * draft. A 503 `payment_provider_unavailable` means nothing changed and the
+     * call can be repeated (the SDK retries it). A `ConflictError` with 409
+     * `payment_setup_failed` means the payment provider refused the request for
+     * the account: it is not retried, and repeating it does not help.
      */
     confirm(id, opts) {
         return this.client.request('POST', `/v1/pre-orders/${encodeURIComponent(id)}/confirm`, undefined, opts);
@@ -52,7 +72,12 @@ export class PreOrdersResource extends BaseResource {
             query: { ...opts?.query, ...query }
         });
     }
-    /** `GET /v1/pre-orders/{id}` — fetch a single pre-order by id. */
+    /**
+     * `GET /v1/pre-orders/{id}` — fetch a single pre-order by id. Reading a
+     * pre-order that is `awaiting_payment` checks its first-month payment: once
+     * it has succeeded, the pre-order comes back in `provisioning`.
+     * `stripe_client_secret` is always `null` here.
+     */
     get(id, opts) {
         return this.client.request('GET', `/v1/pre-orders/${encodeURIComponent(id)}`, undefined, opts);
     }
@@ -69,9 +94,13 @@ export class PreOrdersResource extends BaseResource {
         return this.client.request('PATCH', `/v1/pre-orders/${encodeURIComponent(id)}`, body, opts);
     }
     /**
-     * `POST /v1/pre-orders/{id}/cancel` — cancel a pre-order before it is
-     * fulfilled. Refunds the Stripe payment intent (if charged) and releases the
-     * procurement task. No-op on an already-cancelled / fulfilled pre-order.
+     * `POST /v1/pre-orders/{id}/cancel` — cancel a `draft` or `awaiting_payment`
+     * pre-order. Free: nothing is charged or built in either status. For an
+     * `awaiting_payment` pre-order the first-month payment is voided first, so
+     * its client secret can no longer charge; a first month already paid throws
+     * a `ConflictError` (409 `pre_order_already_paid`). A pre-order that is
+     * `provisioning`, `fulfilled` or already `cancelled` is refused (400
+     * `pre_order_already_confirmed`).
      */
     cancel(id, opts) {
         return this.client.request('POST', `/v1/pre-orders/${encodeURIComponent(id)}/cancel`, undefined, opts);

package/dist/resources/preorders.js.map

@@ -1 +1 @@
-{"version":3,"file":"preorders.js","sourceRoot":"","sources":["../../src/resources/preorders.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAexC,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAwB,EAAE,IAAqB;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAW,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IAC5E,CAAC;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAU,EAAE,IAAqB;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAClD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,QAA4B,EAAE,EAAE,IAAqB;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAmB,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE;YAC/E,GAAG,IAAI;YACP,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE;SACpC,CAAC,CAAA;IACJ,CAAC;IAED,kEAAkE;IAClE,GAAG,CAAC,EAAU,EAAE,IAAqB;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,KAAK,EACL,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAC1C,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,IAAqB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,OAAO,EACP,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAC1C,IAAI,EACJ,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAU,EAAE,IAAqB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,SAAS,EACjD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"preorders.js","sourceRoot":"","sources":["../../src/resources/preorders.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAexC,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAwB,EAAE,IAAqB;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAW,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IAC5E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,EAAU,EAAE,IAAqB;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAClD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,QAA4B,EAAE,EAAE,IAAqB;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAmB,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE;YAC/E,GAAG,IAAI;YACP,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE;SACpC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,EAAU,EAAE,IAAqB;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,KAAK,EACL,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAC1C,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAU,EAAE,IAAuB,EAAE,IAAqB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,OAAO,EACP,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAC1C,IAAI,EACJ,IAAI,CACL,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAU,EAAE,IAAqB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,MAAM,EACN,kBAAkB,kBAAkB,CAAC,EAAE,CAAC,SAAS,EACjD,SAAS,EACT,IAAI,CACL,CAAA;IACH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isnap/sdk",
-  "version": "2.2.0-next.227",
+  "version": "2.2.0-next.228",
   "description": "Official TypeScript SDK for the iSnap P2P telephony API",
   "license": "MIT",
   "type": "module",