@doany-ai/sdk 0.2.8 → 0.3.0-alpha.0

package/dist/modules/orders.types.d.ts

@@ -0,0 +1,215 @@
+import type { Address, Page, PageParams, VersionInput } from "./project.types";
+/**
+ * - `pending`: placed on the site, waiting for its payment; expires after an hour unpaid.
+ * - `placed`: paid, free, or entered by the business. Has an order number.
+ * - `completed`: the business marked it done. Cannot be canceled any more.
+ * - `canceled`, `expired`.
+ */
+export type OrderStatus = "pending" | "placed" | "completed" | "canceled" | "expired";
+export type OrderChannel = "online" | "staff";
+/** Delivery is marked for the whole order. */
+export type FulfillmentStatus = "not_required" | "unfulfilled" | "fulfilled";
+/** A line of an order. Names, price and duration are as they were when it was placed. */
+export interface OrderItem {
+    id: string;
+    variant_id: string | null;
+    item_name: string;
+    variant_name: string | null;
+    duration_minutes: number | null;
+    unit_amount: number;
+    quantity: number;
+    line_amount: number;
+}
+export interface OrderBuyer {
+    name: string;
+    email: string | null;
+    phone: string | null;
+}
+/** An address, plus who receives it (empty: the buyer). */
+export interface ShippingAddress extends Address {
+    name: string | null;
+    phone: string | null;
+}
+export interface Order {
+    id: string;
+    /** Consecutive per business and environment, given when the order is placed. Show it as `#12`. */
+    order_number: number | null;
+    status: OrderStatus;
+    channel: OrderChannel;
+    /** When a `pending` order stops waiting for its payment. */
+    expires_at: string | null;
+    fulfillment_status: FulfillmentStatus;
+    currency: string;
+    /** In the currency's smallest unit (cents). */
+    total_amount: number;
+    /** A test (preview) order or a real one. */
+    livemode: boolean;
+    /** The site it was placed on. */
+    app_id: string | null;
+    contact_id: string | null;
+    /** The account that placed it. */
+    user_id: string | null;
+    buyer: OrderBuyer;
+    shipping_address: ShippingAddress | null;
+    customer_note: string | null;
+    /** Only the site's admin and service callers see it. */
+    internal_note?: string | null;
+    /** In the order they were bought in. */
+    items: OrderItem[];
+    payment: {
+        /** `false` for a free order, which is `placed` as soon as it is created. */
+        required: boolean;
+        amount_received: number;
+        amount_refunded: number;
+    };
+    /** Only the site's admin and service callers see it. */
+    created_by?: "customer" | "owner" | "system";
+    created_by_user_id?: string | null;
+    access?: {
+        issued: boolean;
+        revoked: boolean;
+    };
+    version: number;
+    created_at: string;
+    updated_at: string;
+    placed_at: string | null;
+    completed_at: string | null;
+    canceled_at: string | null;
+}
+export interface OrderSummary {
+    id: string;
+    order_number: number | null;
+    status: OrderStatus;
+    channel: OrderChannel;
+    fulfillment_status: FulfillmentStatus;
+    currency: string;
+    total_amount: number;
+    livemode: boolean;
+    app_id: string | null;
+    contact_id: string | null;
+    user_id: string | null;
+    buyer: {
+        name: string;
+    };
+    created_at: string;
+}
+export interface CreateOrderParams {
+    /** `online` (default): a customer on the site. `staff`: the business entering one. */
+    channel?: OrderChannel;
+    /** The site it is placed on. Defaults to this client's app. */
+    app_id?: string | null;
+    /** 1–100 variants, each once. Prices are not sent: the order takes them from the catalog. */
+    items: Array<{
+        variant_id: string;
+        quantity?: number;
+    }>;
+    /** Who it is for. `email` or `phone` is required; `phone` in E.164 form (`+14155550123`). */
+    buyer: {
+        name: string;
+        email?: string;
+        phone?: string;
+    };
+    /** Required when something in it is shipped (`kind: "physical"`): at least `line` and `country`. */
+    shipping_address?: Partial<ShippingAddress>;
+    /** Up to 1000 characters. */
+    customer_note?: string;
+    /** `staff` only, and required there: a real order or a test. */
+    livemode?: boolean;
+    /** `staff` only: the contact it is for, instead of matching the buyer. */
+    contact_id?: string;
+    /** `staff` only. */
+    internal_note?: string;
+}
+export interface CreateOrderOptions {
+    /**
+     * Identifies this attempt, so that a retry does not place a second order.
+     * Optional: the SDK reuses one key for an identical order that is still in
+     * flight or failed without an answer.
+     */
+    idempotencyKey?: string;
+}
+export interface CreateOrderResult {
+    order: Order;
+    /**
+     * Lets someone who is not signed in open this order again. The SDK keeps it
+     * for the rest of the browser session, so `orders.get`, `orders.cancel` and
+     * the payments calls work without passing it; put it in a link (after `#`)
+     * to reach the order from elsewhere.
+     */
+    access_token?: string;
+    /** `false` when the order is free and already placed. */
+    payment_required: boolean;
+}
+export interface OrderListParams extends PageParams {
+    status?: OrderStatus;
+    channel?: OrderChannel;
+    /** Orders placed on this site. */
+    app_id?: string;
+    /** The contact's orders, and those of contacts merged into it. */
+    contact_id?: string;
+    user_id?: string;
+    /** Order number, buyer name or email. */
+    q?: string;
+    created_from?: string;
+    created_to?: string;
+}
+export interface OrderAccessOptions {
+    /** The order's `access_token`, when it came from a link rather than from this browser session. */
+    accessToken?: string;
+}
+export interface UpdateOrderParams extends VersionInput {
+    /** Not once the order is delivered, completed or closed. */
+    shipping_address?: Partial<ShippingAddress> | null;
+    internal_note?: string | null;
+}
+/**
+ * Orders.
+ *
+ * Who sees an order: the account that placed it, accounts with the records
+ * of its contact, anyone holding its access token, the site's admin and
+ * service callers. Anyone else gets 404.
+ */
+export interface OrdersModule {
+    /**
+     * Places an order for catalog variants. Works signed in or not.
+     *
+     * Rejects with 409 `NOT_PURCHASABLE` (`details.variant_id`, `details.reason`)
+     * when something in it cannot be bought, 409 `MIXED_CURRENCY`, or 429
+     * `RATE_LIMITED`.
+     *
+     * An `online` order takes its environment (preview or published) from the
+     * page's `Origin`, which a backend function does not send: with
+     * `asServiceRole`, enter a `staff` order and say `livemode` instead.
+     *
+     * @example
+     * ```typescript
+     * const { order, payment_required } = await doany.orders.create({
+     *   items: [{ variant_id: variant.id, quantity: 1 }],
+     *   buyer: { name, email },
+     * });
+     * ```
+     */
+    create(params: CreateOrderParams, options?: CreateOrderOptions): Promise<CreateOrderResult>;
+    /** The orders the caller may see, newest first. Rejects with 401 when nobody is signed in. */
+    list(params?: OrderListParams): Promise<Page<OrderSummary>>;
+    /** One order. */
+    get(orderId: string, options?: OrderAccessOptions): Promise<Order>;
+    /** Changes the shipping address or the internal note. The site's admin and service callers only. */
+    update(orderId: string, params: UpdateOrderParams): Promise<Order>;
+    /**
+     * Cancels a `pending` or `placed` order (a customer: only one not paid yet).
+     * Canceling is not refunding. Rejects with 409 `INVALID_STATE` once the
+     * order is completed or expired, 409 `PAYMENT_UNRESOLVED` while a payment
+     * is still being confirmed.
+     */
+    cancel(orderId: string, options?: OrderAccessOptions & Partial<VersionInput>): Promise<Order>;
+    /** Marks the whole order delivered, or takes that back. `placed` orders only. */
+    setFulfillment(orderId: string, params: VersionInput & {
+        status: "fulfilled" | "unfulfilled";
+    }): Promise<Order>;
+    /**
+     * Says the order is done. Nothing may still be owed (409 `INVALID_STATE`,
+     * `details.amount_due`); delivery is not required.
+     */
+    complete(orderId: string, params: VersionInput): Promise<Order>;
+}

package/dist/modules/orders.types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/payments.d.ts

@@ -1,5 +1,6 @@
 import { AxiosInstance } from "axios";
 import { PaymentsModule, ProductsModule } from "./payments.types";
+import { ProjectScope } from "./project.js";
 /**
  * The product reads.
  *
@@ -21,4 +22,4 @@ export declare function createProductsModule(axios: AxiosInstance, appId: string
  *
  * @internal
  */
-export declare function createPaymentsModule(axios: AxiosInstance, appId: string): PaymentsModule;
+export declare function createPaymentsModule(axios: AxiosInstance, appId: string, project: ProjectScope): PaymentsModule;

package/dist/modules/payments.js

@@ -1,3 +1,5 @@
+import { orderAccessHeaders } from "./order-access.js";
+import { queryOf, seg } from "./project.js";
 /**
  * The product reads.
  *
@@ -47,7 +49,7 @@ export function createProductsModule(axios, appId) {
  *
  * @internal
  */
-export function createPaymentsModule(axios, appId) {
+export function createPaymentsModule(axios, appId, project) {
     async function createCheckoutSession(params) {
         const data = await axios.request({
             method: "POST",
@@ -84,5 +86,30 @@ export function createPaymentsModule(axios, appId) {
             });
             return data;
         },
+        // Paying for an order: /projects/{project_id}/orders/{order_id}/...
+        // The order's access token rides along, as for orders.get.
+        async checkout(orderId, params = {}, options) {
+            const data = await axios.request({
+                method: "POST",
+                url: await project.path(`/orders/${seg(orderId)}/checkout`),
+                data: params,
+                headers: orderAccessHeaders(axios, appId, orderId, options === null || options === void 0 ? void 0 : options.accessToken),
+            });
+            return data;
+        },
+        async getForOrder(orderId, options) {
+            const data = await axios.get(await project.path(`/orders/${seg(orderId)}/payments`), {
+                headers: orderAccessHeaders(axios, appId, orderId, options === null || options === void 0 ? void 0 : options.accessToken),
+            });
+            return data;
+        },
+        async list(params = {}) {
+            const data = await axios.get(await project.path("/payments"), { params: queryOf(params) });
+            return data;
+        },
+        async get(paymentId) {
+            const data = await axios.get(await project.path(`/payments/${seg(paymentId)}`));
+            return data;
+        },
     };
 }

package/dist/modules/payments.types.d.ts

@@ -1,3 +1,4 @@
+import type { Page, PageParams } from "./project.types";
 /**
  * One thing being sold in a checkout.
  *
@@ -409,4 +410,149 @@ export interface PaymentsModule {
     createBillingPortalSession(params: BillingPortalParams): Promise<{
         url: string;
     }>;
+    /**
+     * The way to pay for an order: an embedded Stripe checkout (`ui_mode`
+     * `embedded`, the default) or a hosted payment page (`hosted`, returns
+     * `url` — e.g. a payment link to send). One checkout per order at a time:
+     * asking again with the same options answers with the open one.
+     *
+     * Sends the order's access token kept by `orders.create`. Rejects with 404
+     * when the caller may not see the order, 409 `ENVIRONMENT_MISMATCH` when the
+     * page's environment (preview / published) is not the order's, 409
+     * `PAYMENT_UNRESOLVED` while an earlier payment is still being confirmed,
+     * 409 `INVALID_STATE` once the order no longer takes payment.
+     *
+     * @example
+     * ```typescript
+     * const { client_secret, publishable_key, stripe_account } =
+     *   await doany.payments.checkout(order.id, { success_path: `/orders/${order.id}` });
+     * ```
+     */
+    checkout(orderId: string, params?: OrderCheckoutParams, options?: {
+        accessToken?: string;
+    }): Promise<OrderCheckout>;
+    /**
+     * Where an order's payment stands — what a "thank you" page polls: show
+     * success once `order_status` is `placed` (or `completed`), "confirming"
+     * while it is `pending`, and "not paid" when `expired` or `canceled`.
+     * Usually readable 1–3 seconds after paying. Sends the order's access token.
+     */
+    getForOrder(orderId: string, options?: {
+        accessToken?: string;
+    }): Promise<OrderPayments>;
+    /** Payments of the business. The site's admin and service callers only. */
+    list(params?: PaymentListParams): Promise<Page<Payment>>;
+    /** One payment, with its refunds. The site's admin and service callers only. */
+    get(paymentId: string): Promise<Payment>;
+}
+/** How to open an order's checkout. */
+export interface OrderCheckoutParams {
+    /** `embedded` (default): Stripe's form inside the page. `hosted`: Stripe's page, see `url`. */
+    ui_mode?: "embedded" | "hosted";
+    /** The site to come back to; defaults to the one the order was placed on. */
+    app_id?: string;
+    /** A path on the site (`/…`, no `#`, no access token), default `/`. */
+    success_path?: string;
+    cancel_path?: string;
+}
+/** An order's open checkout. */
+export interface OrderCheckout {
+    /** The payment this checkout is. */
+    id: string;
+    status: string;
+    expires_at: string | null;
+    amount_total: number;
+    currency: string;
+    ui_mode: "embedded" | "hosted";
+    /** `embedded`: to load Stripe's form in the page. */
+    client_secret: string | null;
+    publishable_key: string | null;
+    stripe_account: string | null;
+    /** `hosted`: the payment page. */
+    url: string | null;
+    mode: "test" | "live";
+}
+/** The money of one order. */
+export interface OrderPayments {
+    order_id: string;
+    order_status: string;
+    currency: string;
+    total_amount: number;
+    /** What successful payments took. */
+    amount_received: number;
+    /** What successful refunds gave back — kept apart, never netted. */
+    amount_refunded: number;
+    payments: Array<{
+        id: string;
+        status: PaymentStatus;
+        requested_amount: number;
+        received_amount: number;
+        payment_method_type: string | null;
+        paid_at: string | null;
+    }>;
+    refunds: Array<{
+        id: string;
+        payment_id: string;
+        status: RefundStatus;
+        amount: number;
+        succeeded_at: string | null;
+    }>;
+}
+/** `failed` is not final: the same checkout can be paid with another card. */
+export type PaymentStatus = "pending" | "processing" | "requires_action" | "authorized" | "succeeded" | "failed" | "canceled";
+export type RefundStatus = "requested" | "pending" | "succeeded" | "failed" | "canceled";
+export interface Refund {
+    id: string;
+    payment_id: string;
+    amount: number;
+    currency: string;
+    status: RefundStatus;
+    /** Refunds are made in the payment dashboard and synced here (`external`). */
+    origin: "doany" | "external";
+    reason: string | null;
+    failure_code: string | null;
+    provider_refund_id: string | null;
+    provider_status: string | null;
+    succeeded_at: string | null;
+    last_synced_at: string | null;
+    created_at: string | null;
+    version: number;
+}
+export interface Payment {
+    id: string;
+    order_id: string | null;
+    contact_id: string | null;
+    status: PaymentStatus;
+    requested_amount: number;
+    received_amount: number;
+    currency: string;
+    livemode: boolean;
+    /** How it was collected; `null` for a payment recorded by hand. */
+    ui_mode: "embedded" | "hosted" | "direct" | "terminal" | null;
+    /** The site the customer returns to. */
+    app_id: string | null;
+    payment_method_type: string | null;
+    has_dispute: boolean;
+    /** Taken back by a lost dispute. */
+    amount_disputed: number;
+    provider: string | null;
+    provider_account_id: string | null;
+    provider_payment_id: string | null;
+    provider_charge_id: string | null;
+    provider_status: string | null;
+    last_error_code: string | null;
+    paid_at: string | null;
+    last_synced_at: string | null;
+    created_at: string | null;
+    version: number;
+    /** Only in `payments.get`. */
+    refunds?: Refund[];
+}
+export interface PaymentListParams extends PageParams {
+    order_id?: string;
+    contact_id?: string;
+    status?: PaymentStatus;
+    has_dispute?: boolean;
+    created_from?: string;
+    created_to?: string;
 }

package/dist/modules/project.d.ts

@@ -0,0 +1,31 @@
+import { AxiosInstance } from "axios";
+import { AppModule } from "./project.types";
+/**
+ * Where a site's business data lives: `/projects/{project_id}/...`.
+ *
+ * A site knows its app id; the project it belongs to comes from its public
+ * settings, read the first time a business module needs it and then kept.
+ * `createClient({ projectId })` skips the read.
+ *
+ * @internal
+ */
+export interface ProjectScope {
+    /** The project id, as given or as read from the public settings. */
+    projectId(): Promise<string>;
+    /** `/projects/{project_id}` + `path`. */
+    path(path: string): Promise<string>;
+    app: AppModule;
+}
+/** @internal */
+export declare function createProjectScope(axios: AxiosInstance, appId: string, projectId?: string): ProjectScope;
+/** `encodeURIComponent` for one path segment. @internal */
+export declare const seg: (value: string) => string;
+/**
+ * A query string from the params that were actually given: `undefined` and
+ * `null` are left out, booleans become `"true"` / `"false"`.
+ *
+ * @internal
+ */
+export declare function queryOf(params: object | undefined): Record<string, string | number>;
+/** The Idempotency-Key header, when one was given. @internal */
+export declare function idempotencyHeaders(key?: string): Record<string, string>;

package/dist/modules/project.js

@@ -0,0 +1,52 @@
+/** @internal */
+export function createProjectScope(axios, appId, projectId) {
+    let settings = null;
+    function getPublicSettings() {
+        if (!settings) {
+            const reading = axios.get(`/apps/public/prod/public-settings/by-id/${encodeURIComponent(appId)}`);
+            // A failed read is not kept: the next call tries again.
+            settings = reading.catch((error) => {
+                settings = null;
+                throw error;
+            });
+        }
+        return settings;
+    }
+    async function resolveProjectId() {
+        if (projectId)
+            return projectId;
+        const read = await getPublicSettings();
+        if (!(read === null || read === void 0 ? void 0 : read.project_id)) {
+            throw new Error("This app's public settings carry no project_id; pass projectId to createClient()");
+        }
+        return read.project_id;
+    }
+    return {
+        projectId: resolveProjectId,
+        async path(path) {
+            return `/projects/${encodeURIComponent(await resolveProjectId())}${path}`;
+        },
+        app: { getPublicSettings },
+    };
+}
+/** `encodeURIComponent` for one path segment. @internal */
+export const seg = (value) => encodeURIComponent(value);
+/**
+ * A query string from the params that were actually given: `undefined` and
+ * `null` are left out, booleans become `"true"` / `"false"`.
+ *
+ * @internal
+ */
+export function queryOf(params) {
+    const out = {};
+    for (const [key, value] of Object.entries(params !== null && params !== void 0 ? params : {})) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        out[key] = typeof value === "boolean" ? String(value) : value;
+    }
+    return out;
+}
+/** The Idempotency-Key header, when one was given. @internal */
+export function idempotencyHeaders(key) {
+    return key ? { "Idempotency-Key": key } : {};
+}

package/dist/modules/project.types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One page of a list. Every `/projects/...` list answers in this shape.
+ *
+ * Pass `next_cursor` back as `cursor` to get the next page; it is `null` on the
+ * last one. Change the sort and you start again from the first page.
+ */
+export interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+/** What every `/projects/...` list accepts, besides its own filters. */
+export interface PageParams {
+    /** 1–200, default 50. */
+    limit?: number;
+    /** The `next_cursor` of the previous page. */
+    cursor?: string;
+    /** A field name, `-` in front for descending. Each list documents its fields. */
+    sort?: string;
+}
+/** The version a change is based on: send back the `version` you last read. */
+export interface VersionInput {
+    version: number;
+}
+export interface CreateOptions {
+    /**
+     * Makes a retry of the same create answer with the first record instead of
+     * making a second one (16–255 characters). Optional.
+     */
+    idempotencyKey?: string;
+}
+/** An address: every part may be empty; `country` is two upper-case letters. */
+export interface Address {
+    line: string | null;
+    city: string | null;
+    region: string | null;
+    postal_code: string | null;
+    country: string | null;
+}
+/** What a site reads about itself before anything else. */
+export interface AppPublicSettings {
+    /** The app (site) id. */
+    id: string;
+    /** The business the site belongs to: the `/projects/{project_id}/...` APIs are under it. */
+    project_id: string;
+    /** Whatever the site stored; `null` when it stored nothing. */
+    public_settings: unknown;
+}
+/**
+ * The site itself.
+ */
+export interface AppModule {
+    /**
+     * The site's public settings, including the `project_id` its business data
+     * lives under. Read once per client and kept.
+     */
+    getPublicSettings(): Promise<AppPublicSettings>;
+}

package/dist/modules/project.types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/users.d.ts

@@ -1,16 +1,10 @@
 import { AxiosInstance } from "axios";
+import { ProjectScope } from "./project.js";
+import { UsersModule } from "./users.types";
 /**
- * Creates the users module for the Doany SDK
- * @param {AxiosInstance} axios - Axios instance
- * @param {string} appId - Application ID
- * @returns {Object} Users module
+ * Creates the users module: inviting (`/apps/{app_id}/...`) and account
+ * management (`/projects/{project_id}/users/...`).
+ *
+ * @internal
  */
-export declare function createUsersModule(axios: AxiosInstance, appId: string): {
-    /**
-     * Invite a user to the application
-     * @param {string} user_email - User's email address
-     * @param {'user'|'admin'} role - User's role (user or admin)
-     * @returns {Promise<any>}
-     */
-    inviteUser(user_email: string, role: "user" | "admin"): Promise<any>;
-};
+export declare function createUsersModule(axios: AxiosInstance, appId: string, project: ProjectScope): UsersModule;

package/dist/modules/users.js

@@ -1,17 +1,13 @@
+import { queryOf, seg } from "./project.js";
 /**
- * Creates the users module for the Doany SDK
- * @param {AxiosInstance} axios - Axios instance
- * @param {string} appId - Application ID
- * @returns {Object} Users module
+ * Creates the users module: inviting (`/apps/{app_id}/...`) and account
+ * management (`/projects/{project_id}/users/...`).
+ *
+ * @internal
  */
-export function createUsersModule(axios, appId) {
+export function createUsersModule(axios, appId, project) {
+    const users = (suffix = "") => project.path(`/users${suffix}`);
     return {
-        /**
-         * Invite a user to the application
-         * @param {string} user_email - User's email address
-         * @param {'user'|'admin'} role - User's role (user or admin)
-         * @returns {Promise<any>}
-         */
         async inviteUser(user_email, role) {
             if (role !== "user" && role !== "admin") {
                 throw new Error(`Invalid role: "${role}". Role must be either "user" or "admin".`);
@@ -19,5 +15,22 @@ export function createUsersModule(axios, appId) {
             const response = await axios.post(`/apps/${appId}/runtime/users/invite-user`, { user_email, role });
             return response;
         },
+        async list(params = {}) {
+            return (await axios.get(await users(), { params: queryOf(params) }));
+        },
+        async get(userId) {
+            return (await axios.get(await users(`/${seg(userId)}`)));
+        },
+        async disable(userId) {
+            return (await axios.request({ method: "POST", url: await users(`/${seg(userId)}/disable`) }));
+        },
+        async enable(userId) {
+            return (await axios.request({ method: "POST", url: await users(`/${seg(userId)}/enable`) }));
+        },
+        async setContact(userId, contactId) {
+            return (await axios.put(await users(`/${seg(userId)}/contact`), {
+                contact_id: contactId,
+            }));
+        },
     };
 }