@doany-ai/sdk 0.2.1 → 0.2.3

package/README.md

@@ -46,6 +46,7 @@ const client = createClient({
 - `auth` — login, tokens, current user
 - `users` — user management
 - `integrations` — built-in integrations
+- `payments` — take card payments through Stripe
 - `connectors` — third-party connectors
 - `functions` — invoke backend functions
 - `agents` — agent conversations

package/dist/client.js

@@ -6,6 +6,7 @@ import { createSsoModule } from "./modules/sso.js";
 import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFunctionsModule } from "./modules/functions.js";
+import { createPaymentsModule } from "./modules/payments.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
@@ -138,6 +139,7 @@ export function createClient(config) {
             getSocket,
         }),
         integrations: createIntegrationsModule(axiosClient, appId),
+        payments: createPaymentsModule(axiosClient, appId),
         connectors: createUserConnectorsModule(axiosClient, appId),
         auth: userAuthModule,
         functions: createFunctionsModule(functionsAxiosClient, appId, {

package/dist/client.types.d.ts

@@ -4,6 +4,7 @@ import type { AuthModule } from "./modules/auth.types.js";
 import type { SsoModule } from "./modules/sso.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
+import type { PaymentsModule } from "./modules/payments.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
@@ -98,6 +99,8 @@ export interface DoanyClient {
     functions: FunctionsModule;
     /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */
     integrations: IntegrationsModule;
+    /** {@link PaymentsModule | Payments module} for taking card payments through Stripe. */
+    payments: PaymentsModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
     /**

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./mod
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
+export type { PaymentsModule, CheckoutLineItem, CreateCheckoutParams, CreateCheckoutResult, CheckoutSession, SubscriptionState, BillingPortalParams, } from "./modules/payments.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";

package/dist/modules/payments.d.ts

@@ -0,0 +1,13 @@
+import { AxiosInstance } from "axios";
+import { PaymentsModule } from "./payments.types";
+/**
+ * Creates the payments module for the Doany SDK.
+ *
+ * Deliberately thin: every decision that could go wrong — which Stripe
+ * environment, which account, where the customer is sent back to — is made by
+ * the backend from the request's own origin. Nothing here can override it, so
+ * generated app code cannot accidentally charge a real card from a preview.
+ *
+ * @internal
+ */
+export declare function createPaymentsModule(axios: AxiosInstance, appId: string): PaymentsModule;

package/dist/modules/payments.js

@@ -0,0 +1,47 @@
+/**
+ * Creates the payments module for the Doany SDK.
+ *
+ * Deliberately thin: every decision that could go wrong — which Stripe
+ * environment, which account, where the customer is sent back to — is made by
+ * the backend from the request's own origin. Nothing here can override it, so
+ * generated app code cannot accidentally charge a real card from a preview.
+ *
+ * @internal
+ */
+export function createPaymentsModule(axios, appId) {
+    // This client's response interceptor resolves requests to the response body.
+    // Axios's declared return type does not reflect that, so the results below
+    // are cast through `unknown`.
+    return {
+        async createCheckoutSession(params) {
+            const data = await axios.request({
+                method: "POST",
+                url: `/apps/${appId}/payments/checkout-session`,
+                data: params,
+            });
+            return data;
+        },
+        async getSubscription(subscriptionId) {
+            const data = await axios.request({
+                method: "GET",
+                url: `/apps/${appId}/payments/subscription/${encodeURIComponent(subscriptionId)}`,
+            });
+            return data;
+        },
+        async createBillingPortalSession(params) {
+            const data = await axios.request({
+                method: "POST",
+                url: `/apps/${appId}/payments/billing-portal`,
+                data: params,
+            });
+            return data;
+        },
+        async getCheckoutSession(sessionId) {
+            const data = await axios.request({
+                method: "GET",
+                url: `/apps/${appId}/payments/checkout-session/${encodeURIComponent(sessionId)}`,
+            });
+            return data;
+        },
+    };
+}

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

@@ -0,0 +1,228 @@
+/**
+ * One thing being sold in a checkout.
+ *
+ * A line item names a record in your own app data — doany keeps your catalog
+ * there rather than as objects inside Stripe, which is why switching from test
+ * to real payments needs no migration.
+ */
+export type CheckoutLineItem = {
+    /**
+     * The `id` of a record in this app's `Product` entity.
+     *
+     * The price, name and currency all come from that record — you cannot pass
+     * a price. This endpoint is reachable by anyone (a shop has to sell to
+     * visitors who never signed in), so an amount taken from the caller would
+     * let a buyer set their own.
+     */
+    product_id: string;
+    /** Defaults to 1. */
+    quantity?: number;
+};
+export type CreateCheckoutParams = {
+    line_items: CheckoutLineItem[];
+    /**
+     * Three-letter code, lowercase. Defaults to `usd`.
+     *
+     * A `currency` on the `Product` record wins over this, and a product without
+     * one takes this value. All line items in one checkout must end up on the
+     * same currency — Stripe puts it on the session, not the line item — or the
+     * call is refused with `MIXED_CURRENCY_BASKET`.
+     */
+    currency?: string;
+    /**
+     * Where the customer lands after paying, as a path on your own site.
+     *
+     * Must be a path, not a full URL — the origin is added for you, which is
+     * what guarantees a checkout started in the preview comes back to the
+     * preview rather than to your published site.
+     *
+     * `session_id` is appended so the page can confirm the payment.
+     */
+    success_path?: string;
+    /** Where the customer lands if they abandon checkout. Also a path. */
+    cancel_path?: string;
+    /** Prefills the email field. Skip it and Stripe asks. */
+    customer_email?: string;
+    /** Your own data, returned with the order. Up to 20 keys. */
+    metadata?: Record<string, string>;
+};
+export type CreateCheckoutResult = {
+    id: string;
+    /** Send the customer here. */
+    url: string;
+    /** `test` in the preview, `live` on a published site that has gone live. */
+    mode: "test" | "live";
+    /**
+     * What the customer is about to agree to, decided by the catalog.
+     *
+     * `subscription` when the products carry a `recurring_interval`, `payment`
+     * otherwise. Say the right word on the button: "Subscribe" over a one-off
+     * charge, or "Buy" over a recurring one, is a complaint waiting to happen.
+     */
+    billing: "payment" | "subscription";
+    /** `month` / `year` / `week` for a subscription, `null` for a one-off. */
+    interval: string | null;
+};
+export type SubscriptionState = {
+    id: string;
+    mode: "test" | "live";
+    /** Stripe's own vocabulary: active / trialing / past_due / canceled / unpaid /
+     *  incomplete / incomplete_expired / paused. */
+    status: string;
+    /** THE field to gate access on — true for `active` and `trialing`. */
+    active: boolean;
+    /** Cancelled, but the period they already paid for is still running.
+     *  Keep access until `current_period_end`. */
+    cancel_at_period_end: boolean;
+    current_period_end: number | null;
+    canceled_at: number | null;
+    customer_id: string | null;
+    interval: string | null;
+    amount: number | null;
+    currency: string | null;
+    metadata: Record<string, string>;
+};
+export type BillingPortalParams = {
+    /** From `getCheckoutSession(...).customer_id`. Store it when they subscribe. */
+    customer_id: string;
+    /** Where Stripe returns them, as a path on your own site. */
+    return_path?: string;
+};
+export type CheckoutSession = {
+    id: string;
+    mode: "test" | "live";
+    /** The one field a success page should branch on. */
+    paid: boolean;
+    payment_status: string;
+    amount_total: number | null;
+    currency: string | null;
+    customer_email: string | null;
+    /**
+     * Whether the money came back, in three honest states.
+     *
+     * Computed from the amounts rather than from Stripe's own `refunded` flag,
+     * which is only true for a FULL refund — an app reading that flag keeps
+     * serving someone who was refunded most of their money.
+     *
+     * Re-read this before granting access to anything valuable; a checkout that
+     * was `paid` in March can be `full` in April.
+     */
+    refund_status: "none" | "partial" | "full";
+    /** Minor units, same scale as `amount_total`. */
+    amount_refunded: number;
+    /** The customer went to their bank. Money is already gone, whatever the
+     *  refund status says. */
+    disputed: boolean;
+    /** `subscription` when this checkout started a plan. */
+    billing: "payment" | "subscription";
+    /** Present for a subscription checkout. Store it — it is what reads the
+     *  plan's state on every later page load. */
+    subscription_id: string | null;
+    /** Store this too: it is what opens the billing portal so the customer can
+     *  cancel, without the app being given any power over subscriptions. */
+    customer_id: string | null;
+    line_items: Array<{
+        name: string | null;
+        quantity: number | null;
+        amount_total: number | null;
+    }>;
+    metadata: Record<string, string>;
+};
+/**
+ * Take card payments on your site.
+ *
+ * Money goes to the app owner's own Stripe account — doany never holds it and
+ * takes no cut. Stripe's usual per-transaction fee applies.
+ *
+ * ## Prices live in your data, not in your code
+ *
+ * Sellable things are records in this app's `Product` entity, with the price in
+ * an integer `price_cents` field. A checkout names the product; the server
+ * looks up what it costs.
+ *
+ * ## Test and real payments
+ *
+ * Which one you get is decided by the address the site is served from, not by
+ * anything in your code:
+ *
+ * - **Preview** — test payments. Card `4242 4242 4242 4242` with any future
+ *   expiry runs the whole flow and charges nothing.
+ * - **Published site** — real payments, once the owner has gone live from the
+ *   Payments panel. Before that, {@linkcode PaymentsModule.createCheckoutSession}
+ *   fails with `PAYMENTS_NOT_LIVE` rather than quietly taking no money.
+ *
+ * The same code covers both. There is no key to configure and no mode to set.
+ */
+export interface PaymentsModule {
+    /**
+     * Opens a Stripe checkout and returns the URL to send the customer to.
+     *
+     * @example Sell one item
+     * ```typescript
+     * // The price comes from the Product record, not from this call.
+     * const { url } = await doany.payments.createCheckoutSession({
+     *   line_items: [{ product_id: product.id, quantity: 1 }],
+     *   success_path: '/thanks',
+     *   cancel_path: '/shop',
+     *   metadata: { order_id: order.id },
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    createCheckoutSession(params: CreateCheckoutParams): Promise<CreateCheckoutResult>;
+    /**
+     * Reads a checkout back — what a success page calls to confirm the payment.
+     *
+     * Confirm here rather than waiting for a webhook: the customer is already
+     * looking at your thank-you page, and the webhook may not have arrived.
+     *
+     * @example Confirm on the success page, once
+     * ```typescript
+     * const sessionId = new URLSearchParams(location.search).get('session_id');
+     * const session = await doany.payments.getCheckoutSession(sessionId);
+     * if (session.paid) {
+     *   // Key the fulfilment on session.id so a refresh cannot deliver twice.
+     *   await Order.update(session.metadata.order_id, { status: 'paid' });
+     * }
+     * ```
+     */
+    getCheckoutSession(sessionId: string): Promise<CheckoutSession>;
+    /**
+     * Is this plan still active?
+     *
+     * Call it on every page that gates something behind a plan. A subscription
+     * outlives the checkout that created it and changes without your app doing
+     * anything — renewals, a failed card, a cancellation made in the portal — so
+     * a value stored at signup goes stale on its own.
+     *
+     * @example Gate a page
+     * ```typescript
+     * const plan = await doany.payments.getSubscription(user.subscription_id);
+     * if (!plan.active) return <Upgrade />;
+     * if (plan.cancel_at_period_end) {
+     *   // still paid up — keep access, but say when it ends
+     * }
+     * ```
+     */
+    getSubscription(subscriptionId: string): Promise<SubscriptionState>;
+    /**
+     * Opens Stripe's own page for cancelling, switching plan, or fixing a card.
+     *
+     * This is why there is no `cancelSubscription` here: cancelling happens on
+     * Stripe's hosted page, so no endpoint in your app can modify a
+     * subscription, and a bug in your code cannot cancel somebody's plan. What
+     * the page offers is configured by the app owner in their Stripe dashboard.
+     *
+     * @example A "Manage billing" button
+     * ```typescript
+     * const { url } = await doany.payments.createBillingPortalSession({
+     *   customer_id: user.stripe_customer_id,
+     *   return_path: '/account',
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    createBillingPortalSession(params: BillingPortalParams): Promise<{
+        url: string;
+    }>;
+}

package/dist/modules/payments.types.js

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

package/package.json

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