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

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,
+            }));
+        },
     };
 }

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

@@ -0,0 +1,62 @@
+import type { Page, PageParams } from "./project.types";
+/**
+ * An account of the site's business, as account management shows it: the
+ * account's public fields (plus any custom fields saved with `auth.updateMe`)
+ * and how it signs in.
+ */
+export interface UserRecord {
+    id: string;
+    email: string;
+    full_name: string | null;
+    /** `user`, `admin`, or a role the site defines. */
+    role: string;
+    /** Whether the email is verified. */
+    verified: boolean;
+    created_date: string | null;
+    updated_date: string | null;
+    status: "active" | "disabled";
+    /** `unknown`: an account migrated without a password. */
+    created_via: "email" | "oauth" | "invite" | "preview" | "unknown";
+    /** The account's own contact; may be empty until its email is verified. */
+    contact_id: string | null;
+    /** The site it signed up on. */
+    app_id: string | null;
+    last_signed_in_at: string | null;
+    /** e.g. `["email", "google"]`. */
+    login_methods: string[];
+    /** Custom fields saved with `auth.updateMe`. */
+    [field: string]: unknown;
+}
+export interface UserListParams extends PageParams {
+    /** Part of the email or name. */
+    q?: string;
+    status?: "active" | "disabled";
+    /** Accounts linked to this contact. */
+    contact_id?: string;
+    /** Accounts that signed up on this site. */
+    app_id?: string;
+}
+/**
+ * The site's accounts.
+ *
+ * `list` / `get` show a signed-in account only itself; the site's admin and
+ * service callers see every account. Disabling, enabling and setting the
+ * contact take the site's admin account or a service credential.
+ */
+export interface UsersModule {
+    /**
+     * Invites someone by email; they set a password from the link they get.
+     * Only the site's admin (or a service caller) may invite an admin.
+     */
+    inviteUser(user_email: string, role: "user" | "admin"): Promise<any>;
+    list(params?: UserListParams): Promise<Page<UserRecord>>;
+    get(userId: string): Promise<UserRecord>;
+    /** The account can no longer sign in, and the tokens it holds stop working. */
+    disable(userId: string): Promise<UserRecord>;
+    enable(userId: string): Promise<UserRecord>;
+    /**
+     * Makes a contact the account's own (it sees that contact's orders and buys
+     * as it); `null` unlinks. For correcting an automatic link that went wrong.
+     */
+    setContact(userId: string, contactId: string | null): Promise<UserRecord>;
+}

package/dist/modules/users.types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doany-ai/sdk",
-  "version": "0.2.9-alpha.0",
+  "version": "0.3.0-alpha.0",
   "description": "JavaScript SDK for the doany app platform (API-compatible fork of @base44/sdk)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",