@doany-ai/sdk

JavaScript/TypeScript SDK for the doany app platform.

This is an API-compatible MIT fork of @base44/sdk. It includes Base44-compatible entity, auth and integration modules, plus DoAny-specific Catalog, Orders and Plan-rights APIs described below.

Install

npm i @doany-ai/sdk

Quickstart

import { createClient } from '@doany-ai/sdk';

// Defaults to serverUrl: https://api.doany.ai
const client = createClient({
  appId: 'your-app-id',
});

// Entities: CRUD on your app's data
const products = await client.entities.Products.list();
await client.entities.Products.create({ name: 'Widget', price: 9.99 });

// Auth: current user
const me = await client.auth.me();

For local development, override the server URL:

const client = createClient({
  appId: 'your-app-id',
  serverUrl: 'http://localhost:8000',
});

Modules

• entities — CRUD, filtering, realtime subscriptions
• auth — login, tokens, current user
• users — user management
• integrations — built-in integrations
• payments — take card payments through Stripe
• subscriptions — a Plan billed by the period: start one, read the account's
• entitlements — the rights the signed-in account holds
• calendar — book the business's services: appointments and class seats; with a service credential, also the business's roster (registrations.list, e.g. one client's by contact_id) and bookings (bookings.*, sessions.cancel)
• forms — render and submit the business's forms
• connectors — third-party connectors
• functions — invoke backend functions
• agents — agent conversations
• aiGateway — AI gateway (LLM calls)
• analytics — analytics events
• appLogs — app logging
• sso — single sign-on
• asServiceRole — service-role scoped client

Services and acquired Plan rights

catalog.list({ service_mode: "order", purchasable: true }) reads explicit direct-order services. service_mode is booking, order or inquiry; null remains unclassified. The optional payment_requirement is the Catalog default: full_online requires payment before website confirmation; none does not require advance payment. Inquiry has no Catalog payment policy. Charged Order services with none currently require merchant-entered orders; website checkout refuses them. Zero is free and no price is not free. Follow purchasable for the website purchase action.

A merchant/operator can confirm an Inquiry quote through orders.create with channel: "staff", quote_confirmed: true, currency, livemode and an agreed unit_amount on every Inquiry item. new_client and contact_id are alternative client choices. Site administrators and site service credentials cannot bypass merchant authorization. The resulting placed order may be unpaid; creating it collects no money and marks no service complete. Items optionally expose the frozen service mode and policy.

Read one client's balances with catalog.listPlanIssues({ contact_id }) (a signed-in customer lists their own without it), and one with catalog.getPlanIssue(issueId). Merchant reads include normal service uses and allowed_actions.use. Consumption checks the customer's frozen targets, balance and validity rather than today's Plan definition:

const result = await client.catalog.usePlanIssue(issueId, {
  entitlement_id: benefit.entitlement_id,
  catalog_item_id: service.id,
  catalog_item_variant_id: variant.id,
  units: 1,
  reason: "Service provided",
}, { idempotencyKey: operationKey });

await client.catalog.reversePlanIssueUse(issueId, result.use_id, {
  reason: "Service entered twice",
});

Both mutations require merchant authorization. Reuse operationKey when retrying one use; reversal retries cannot return units twice. This records normal use of previously acquired rights and creates no charge or financial order. Calendar registration uses remain managed by Calendar.

License

MIT — see LICENSE.

Booking-order cancellation uses the ordinary Orders API: orders.cancel(orderId, { version, reason?, refundDecision?, idempotencyKey?, accessToken? }). For an ordinary order with money still received, business callers must supply refundDecision: "refund" | "keep"; omission returns REFUND_DECISION_REQUIRED and leaves the order unchanged. Managed bookings use their cancellation policy. Reasons are optional for every order. A successful HTTP response can mean the request was only accepted: cancellation.status === "processing" requires polling orders.get, not another cancellation. not_canceled means the booking was not canceled (for example, its payment completed); confirm the customer's intent again before sending a new request. Reuse an idempotency key for retries of one request, and use a new key for a new decision.

The Calendar entry calendar.context() includes preview: the backend identifies the website address independently of the signed-in account. Preview addresses support reading services and times but refuse booking writes with 409 INVALID_STATE and details.reason="preview_only"; use the published website for a real booking.