@makemind/sdk 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,80 @@ All notable changes to `@makemind/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.1 — 2026-10-12
+
+### Fixed
+
+- `ai.analyzeDocument()` sends the document. It used to send the words
+  "Document URL: …" to a chat model, which never saw the document and answered
+  anyway. The document goes as a `document` part (an https address or a data
+  URI), and only a model that reads PDFs is chosen for it.
+
+### Added
+
+- `ai.ocr(document, { pages?, mediaType?, model? })` — the document's text as
+  written, page by page and line by line with confidence and position; at most
+  30 pages per call, `more` while a next window may hold pages.
+
+## 0.2.0 — 2026-10-09
+
+### Changed — breaking
+
+- Pages carry `dsl` (an MCP UI DSL page) in place of `components`, `layout`,
+  `variables`, `dataSources` and `events`; apps carry `definition` (theme,
+  navigation, languages) and `rollout`. `ComponentNode` is replaced by
+  `DslNode` / `DslPage`.
+- `apps.generateUI` returns `{ content }` — a DSL widget subtree.
+  `apps.suggestActions(appId, widgetType?)` returns DSL actions.
+- `apps.publish(appId, changelog?, { rolloutPercent })` publishes to a share of
+  visitors.
+
+### Added
+
+- `recordSaleWithShares({ delivered })` — what went out with the sale (name,
+  quantity, unit, item id), recorded beside the money.
+- `reverseSaleWithShares({ returnedQuantity })` — units that came back. Without
+  it a partial refund is a price adjustment and the refund that completes the
+  sale returns every unit still out.
+
+### Removed (breaking)
+
+- `signUp`, `sendPasswordResetEmail`, `confirmPasswordReset` and `verifyEmail`.
+  The routes behind them were removed from the platform on 2026-09-17 and
+  answer `404`, so every call could only fail. A published client that offers
+  an operation the server does not have is a promise its caller discovers is
+  false at runtime.
+
+  What replaces them: a platform account exists once its person signs in at the
+  tenant portal; a tenant's own end users register in that tenant's pool
+  (`endusers-selfRegisterEndUser`). Sign-in (`signInWithEmail`,
+  `signInWithOAuthToken`) and `updatePassword` for a signed-in person are
+  unchanged.
+
+## 0.1.1 — 2026-09-12
+
+### Fixed
+
+- The `data` service spanned two stores. `create`, `get`, `update` and `delete` went through the
+  REST data door — a separate tree that admits only a fixed set of collection names — while
+  `query`, the batch methods, `aggregate` and `search` address the document platform. A document
+  created with `create` was invisible to `query` and refused by `batchDelete`, and a collection
+  of your own naming was refused by `create` outright. All four now address the document
+  platform: ids are `DOC_…`, `get` answers `{ id, data }`, and a collection is taken as named.
+- `refreshAuthToken()` signed the user out — and revoked their refresh tokens server-side — when
+  the gateway answered that no refresh token was sent. That is the answer every client without the
+  refresh cookie gets (a server-side process, for one), and its id token is still valid. It now
+  keeps the session and raises `MAKEMINDError('AUTH_REFRESH_UNAVAILABLE')`; a refresh token the
+  server refused still signs out. `createTenant` and `switchTenant` refresh internally, so a
+  server-side consumer signs in again after them to pick up the new claims.
+
+- `batchCreate`, `batchUpdate` and `batchDelete` reported a batch the backend partly refused as
+  written. `dataBatchWrite` answers per item, and an item it will not perform comes back
+  `status: 'denied'` with a reason (`DATA_ALREADY_EXISTS`, `DATA_WRITE_ONCE_VIOLATION`,
+  `AUTH_ACCESS_DENIED`) while the rest commit. A denied item now raises
+  `MAKEMINDError('BATCH_PARTIALLY_DENIED')`, whose `details.results` lists every item and
+  `details.denied` the refused ones.
+
 ## 0.1.0
 
 First release. The public surface is not frozen: while this package is 0.x, a minor bump may change it.

package/README.md

@@ -61,14 +61,11 @@ initializeMAKEMIND({
 ```typescript
 const makemind = getMAKEMIND();
 
-// Sign in with email + password
+// Sign in with email + password. There is no sign-up here: a platform account
+// exists once its person signs in at the tenant portal, and a tenant's own end
+// users register in that tenant's pool (`endusers-selfRegisterEndUser`).
 const user = await makemind.auth.signInWithEmail(email, password);
 
-// Sign up a new user
-const newUser = await makemind.auth.signUp(email, password, {
-  displayName: 'Jane Doe',
-});
-
 // Listen to auth state changes
 const unsubscribe = makemind.auth.onAuthStateChanged((user) => {
   if (user) {
@@ -88,6 +85,12 @@ const memberships = await makemind.auth.getUserMemberships();
 await makemind.auth.switchTenant('new-tenant-id');
 ```
 
+The refresh token is an HttpOnly cookie, so only a browser can refresh a session. A
+server-side process keeps its id token until it expires; `refreshAuthToken()` there raises
+`AUTH_REFRESH_UNAVAILABLE` and leaves the session intact. `createTenant` and `switchTenant`
+refresh internally, so on a server sign in again after them to pick up the new claims — or use
+an API key, which is the credential made for machine callers.
+
 ## Data Operations
 
 ```typescript
@@ -110,7 +113,8 @@ const product = await makemind.data.get({
   documentId: 'product-id',
 });
 
-// Create document (tenant_id auto-added)
+// Create document — every data method addresses the same document store,
+// under whatever collection name you give it; ids are DOC_-prefixed
 const result = await makemind.data.create({
   collection: 'plm_products',
   data: {

package/dist/index.d.mts

@@ -224,6 +224,19 @@ declare class MAKEMINDSettlement {
             description?: string;
             metadata?: Record<string, unknown>;
         }>;
+        /**
+         * What went out with the sale, recorded beside the money — at a price of
+         * nought too. One line per sale, at the gross.
+         */
+        delivered?: {
+            name: string;
+            /** Defaults to 1. */
+            quantity?: number;
+            unit?: string;
+            productId?: string;
+            itemRef?: string;
+            subscriptionId?: string;
+        };
     }): Promise<{
         transactionId: string;
         shareTransactionIds: (string | null)[];
@@ -243,6 +256,13 @@ declare class MAKEMINDSettlement {
     reverseSaleWithShares(options: {
         transactionId: string;
         amount?: number;
+        /**
+         * Units that came back, when you know. Without it the ledger never guesses
+         * units from money: a refund short of the whole is a price adjustment (the
+         * thing stays delivered), and the refund that completes it returns every
+         * unit still out.
+         */
+        returnedQuantity?: number;
         reason?: string;
         idempotencyKey: string;
     }): Promise<{
@@ -583,12 +603,7 @@ declare class MAKEMINDAuth {
     loadMemberships(): Promise<TenantMembership[]>;
     signInWithEmail(email: string, password: string): Promise<AuthUser>;
     signInWithEmailAndPassword(email: string, password: string): Promise<AuthUser>;
-    signUp(email: string, password: string, options?: {
-        displayName?: string;
-        phoneNumber?: string;
-    }): Promise<AuthUser>;
     signOut(): Promise<void>;
-    sendPasswordResetEmail(email: string): Promise<void>;
     onAuthStateChanged(callback: AuthStateCallback): () => void;
     private notifyAuthStateCallbacks;
     refreshAuthToken(): Promise<void>;
@@ -617,14 +632,6 @@ declare class MAKEMINDAuth {
      * Backend dispatch 'resendVerificationEmail' — uid resolved from auth context, no payload needed.
      */
     sendEmailVerification(): Promise<void>;
-    /**
-     * Verify email with code
-     */
-    verifyEmail(code: string): Promise<void>;
-    /**
-     * Confirm password reset with code
-     */
-    confirmPasswordReset(code: string, newPassword: string): Promise<void>;
     /**
      * OAuth redirect-based sign-in is NOT supported by this backend.
      * The backend has no /oauth/initiate or /oauth/callback routes.
@@ -707,6 +714,17 @@ declare class MAKEMINDData {
         data: Record<string, unknown>;
         documentId?: string;
     }>): Promise<Array<DocumentResult<T>>>;
+    /**
+     * Send a batch and refuse to report a partial one as whole.
+     *
+     * The backend answers per item: an item it would not perform comes back
+     * `status: 'denied'` with the reason (`DATA_ALREADY_EXISTS` for a create over
+     * an id that exists, `DATA_WRITE_ONCE_VIOLATION`, `AUTH_ACCESS_DENIED`) while
+     * the others commit. Reading only the ids told the caller every item was
+     * written. A denied item now raises `BATCH_PARTIALLY_DENIED`, and the error
+     * carries every item's result so the caller can see which ones did commit.
+     */
+    private batchWrite;
     batchUpdate(collection: string, updates: Array<{
         documentId: string;
         data: Record<string, unknown>;
@@ -1889,6 +1907,30 @@ interface ToolDefinition {
     description: string;
     parameters: Record<string, unknown>;
 }
+/** One line an OCR engine read: its text, confidence and box (0–1: left, top, right, bottom). */
+interface OcrLine {
+    text: string;
+    confidence: number;
+    box: [number, number, number, number];
+}
+/** One page an OCR engine read. */
+interface OcrPage {
+    number: number;
+    width: number;
+    height: number;
+    text: string;
+    confidence: number;
+    lines: OcrLine[];
+}
+/** What `ocr()` answers: the pages read, and whether a next window may hold more. */
+interface OcrResult {
+    requestId: string;
+    model: string;
+    pages: OcrPage[];
+    more: boolean;
+    cost: number;
+    currency?: string;
+}
 declare class MAKEMINDAI {
     private apiClient;
     private getTenantId;
@@ -1973,20 +2015,35 @@ declare class MAKEMINDAI {
     }>;
     /**
      * Document analysis (summary, field extraction, or QA).
-     * No dedicated onCall exists in the ai domain; implemented via ai-aiChat
-     * with a structured system prompt that targets the requested analysis type.
-     * The document content must be fetched by the caller and passed as text —
-     * the backend has no URL-fetch / OCR pipeline for onCall yet.
+     * The document itself is sent — a PDF as a `document` part, which the
+     * platform hands only to a model that reads PDFs (core-ai 18 §5.2). `document`
+     * is an https address the platform reads, or a `data:application/pdf;base64,…`
+     * URI.
      */
-    analyzeDocument(documentUrl: string, analysisType: 'summary' | 'extract' | 'qa', options?: {
+    analyzeDocument(document: string, analysisType: 'summary' | 'extract' | 'qa', options?: {
         question?: string;
         extractFields?: string[];
+        model?: string;
     }): Promise<{
         result: string | Record<string, unknown>;
         usage: {
             totalTokens: number;
         };
     }>;
+    /**
+     * A document's text as written, page by page and line by line, from an OCR
+     * engine — each line with its confidence and its box on the page (core-ai 18
+     * §5.3). One call reads at most 30 pages; read the next window while `more`.
+     * `document` is an https address or a data URI (PDF, PNG, JPEG, TIFF).
+     */
+    ocr(document: string, options?: {
+        pages?: {
+            from?: number;
+            to?: number;
+        };
+        mediaType?: string;
+        model?: string;
+    }): Promise<OcrResult>;
     generate(prompt: string, options?: ChatOptions): Promise<{
         text: string;
         usage: {
@@ -2099,7 +2156,6 @@ declare class MAKEMINDSearch {
  */
 
 type AppStatus = 'draft' | 'published' | 'archived';
-type LayoutType = 'blank' | 'sidebar' | 'topnav' | 'dashboard' | 'centered';
 type SSLStatus = 'pending' | 'provisioning' | 'active' | 'expired' | 'failed';
 type CustomDomainStatus = 'pending' | 'verifying' | 'active' | 'failed';
 /** Where a hostname's traffic is routed once it reaches the domain-serving edge. */
@@ -2208,18 +2264,17 @@ interface App {
     publishedVersion: number | null;
     domain: DomainConfig;
     settings: AppSettings;
+    definition?: AppDefinition;
+    /** A version served to a share of visitors beside the published one. */
+    rollout?: {
+        version: number;
+        percent: number;
+    };
     createdAt: string;
     createdBy: string;
     updatedAt: string;
     updatedBy: string;
 }
-interface LayoutConfig {
-    sidebarWidth?: number;
-    sidebarCollapsible?: boolean;
-    headerHeight?: number;
-    footerHeight?: number;
-    contentMaxWidth?: number;
-}
 interface PageSEO {
     title: string;
     description: string;
@@ -2227,61 +2282,42 @@ interface PageSEO {
     noIndex?: boolean;
 }
 /**
- * A node of a builder page, as stored and as the API returns it.
- *
- * This described nine of the tree's fields while the editor writes fifteen:
- * `dataBinding`, `validation`, `a11y` and `conditions.className` were absent
- * entirely. TypeScript does not delete what it cannot see, so a round trip
- * through `getPage`/`updatePage` kept them — but a consumer BUILDING a node
- * from this type had no way to express a binding or a validation rule, and
- * one rebuilding a node field-by-field dropped them silently.
+ * A widget of a page document — MCP UI DSL 1.4 (app builder DDD 08 §2).
  *
- * `type` stays `string` rather than the editor's 108-member union: this
- * describes a REST payload, and the palette must be able to grow without
- * every SDK consumer needing a new release to accept the new type.
- *
- * Kept in step with `@makemind/app-builder-ui`'s `ComponentNode` by
- * `src/__tests__/component-node-parity.test.ts`.
+ * `type` is a widget type the spec defines; every node the builder holds
+ * carries `x-id`. The other properties are the widget's own, as the spec
+ * declares them, so they are not enumerated here.
  */
-interface ComponentNode {
-    id: string;
+interface DslNode {
     type: string;
-    name: string;
-    props: Record<string, unknown>;
-    styles: Record<string, unknown>;
-    children?: ComponentNode[];
-    conditions?: {
-        visible?: string;
-        enabled?: string;
-        className?: string;
+    'x-id'?: string;
+    [prop: string]: unknown;
+}
+/** A page document (page.schema). */
+interface DslPage {
+    type: 'page';
+    title?: string;
+    content: DslNode;
+    state?: {
+        initial?: Record<string, unknown>;
     };
-    events?: Record<string, unknown[]>;
-    dataBinding?: {
-        source: string;
-        field: string;
-        transform?: string;
+    lifecycle?: Record<string, unknown>;
+    [prop: string]: unknown;
+}
+/** Theme, navigation, languages and app state — the DSL around the pages. */
+interface AppDefinition {
+    title?: string;
+    theme?: Record<string, unknown>;
+    navigation?: {
+        type: 'drawer' | 'bottomBar' | 'rail' | 'tabs';
+        items?: unknown[];
+        [key: string]: unknown;
     };
-    validation?: Array<{
-        type: string;
-        value?: unknown;
-        message: string;
-    }>;
-    a11y?: {
-        label?: string;
-        description?: string;
-        role?: string;
+    i18n?: Record<string, unknown>;
+    state?: {
+        initial?: Record<string, unknown>;
     };
-}
-interface DataSource {
-    id: string;
-    name: string;
-    type: 'query' | 'document' | 'api' | 'flow' | 'variable' | 'realtime';
-    config: Record<string, unknown>;
-}
-interface PageVariable {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-    defaultValue: unknown;
+    [key: string]: unknown;
 }
 interface Page {
     id: string;
@@ -2293,13 +2329,8 @@ interface Page {
     isHomePage: boolean;
     isPublic: boolean;
     accessRoles: string[];
-    layout: {
-        type: LayoutType;
-        config: LayoutConfig;
-    };
-    components: ComponentNode[];
-    dataSources: DataSource[];
-    variables: PageVariable[];
+    /** The page document the runner draws. */
+    dsl: DslPage;
     seo: PageSEO;
     order: number;
     createdAt: string;
@@ -2373,6 +2404,13 @@ interface UpdateAppParams {
     icon?: string;
     status?: AppStatus;
     settings?: AppSettings;
+    /** Replaces the app definition as a whole. */
+    definition?: AppDefinition;
+    /** Adjust a rollout; `percent: 100` promotes it, `null` ends it. */
+    rollout?: {
+        version: number;
+        percent: number;
+    } | null;
 }
 interface ListAppsParams {
     status?: AppStatus;
@@ -2386,10 +2424,9 @@ interface CreatePageParams {
     description?: string;
     isHomePage?: boolean;
     isPublic?: boolean;
-    layout?: {
-        type: LayoutType;
-        config?: LayoutConfig;
-    };
+    /** The page document; an empty column when absent. */
+    dsl?: DslPage;
+    seo?: Partial<PageSEO>;
 }
 interface UpdatePageParams {
     name?: string;
@@ -2399,13 +2436,8 @@ interface UpdatePageParams {
     isHomePage?: boolean;
     isPublic?: boolean;
     accessRoles?: string[];
-    layout?: {
-        type: LayoutType;
-        config?: LayoutConfig;
-    };
-    components?: ComponentNode[];
-    dataSources?: DataSource[];
-    variables?: PageVariable[];
+    /** Replaces the page document as a whole. */
+    dsl?: DslPage;
     seo?: PageSEO;
 }
 interface MAKEMINDAppsConfig extends MAKEMINDConfig {
@@ -2443,7 +2475,13 @@ declare class MAKEMINDApps {
     duplicatePage(appId: string, pageId: string, newName?: string, newPath?: string): Promise<{
         pageId: string;
     }>;
-    publish(appId: string, changelog?: string): Promise<{
+    /**
+     * Cut a version and publish it — to everyone, or with `rolloutPercent`
+     * (1–99) to that share of visitors beside the published version.
+     */
+    publish(appId: string, changelog?: string, options?: {
+        rolloutPercent?: number;
+    }): Promise<{
         success: boolean;
         version: number;
         publishedAt: string;
@@ -2661,11 +2699,16 @@ declare class MAKEMINDApps {
         startDate?: string;
         endDate?: string;
     }): Promise<AppAnalytics>;
+    /** A widget subtree in DSL from a description (app builder DDD 08 §9). */
     generateUI(prompt: string, context?: Record<string, unknown>, appId?: string): Promise<{
-        components: ComponentNode[];
+        content: DslNode;
     }>;
-    suggestActions(appId: string, componentType?: string, context?: Record<string, unknown>): Promise<{
-        actions: unknown[];
+    /** DSL actions a widget could run, from the tools the app's origin offers. */
+    suggestActions(appId: string, widgetType?: string): Promise<{
+        suggestions: Array<{
+            label: string;
+            action: Record<string, unknown>;
+        }>;
     }>;
     startSession(appId: string, pageId: string): Promise<{
         sessionToken: string;
@@ -3067,6 +3110,8 @@ declare const ErrorCodes: {
     readonly NOT_FOUND: "NOT_FOUND";
     readonly ALREADY_EXISTS: "ALREADY_EXISTS";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    /** No refresh credential on this client; the session is intact but cannot be refreshed here. */
+    readonly AUTH_REFRESH_UNAVAILABLE: "AUTH_REFRESH_UNAVAILABLE";
     readonly TENANT_NOT_FOUND: "TENANT_NOT_FOUND";
     readonly TENANT_SUSPENDED: "TENANT_SUSPENDED";
     readonly NOT_A_MEMBER: "NOT_A_MEMBER";
@@ -3077,4 +3122,4 @@ declare const ErrorCodes: {
     readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
 };
 
-export { ApiClient, type ApiClientConfig, type ApiRequestOptions, type AuthStateCallback, type AuthUser, type BillingSummary, type CollectionSnapshotCallback, type ConsultResult, type ConsultationConclusion, type CreateOptions, type DeleteOptions, type DocumentResult, ErrorCodes, type ExpertAccess, ExpertChat, type ExpertChatWidget, type ExpertChatWidgetOptions, type ExpertConsultation, ExpertDoorError, type ExpertSession, type ExpertTurn, type FileMetadata, type FlowListItem, type GetOptions, type Invoice, type ListFilesOptions, type ListFilesResult, type ListFlowsParams, type ListFlowsResult, type LogicCallResult, MAKEMINDAI, type MAKEMINDAIConfig, MAKEMINDApps, type MAKEMINDAppsConfig, MAKEMINDAuth, type MAKEMINDAuthConfig, MAKEMINDClient, type MAKEMINDClientConfig, type MAKEMINDConfig, MAKEMINDData, type MAKEMINDDataConfig, MAKEMINDError, MAKEMINDExperts, type MAKEMINDExpertsConfig, MAKEMINDLogic, type MAKEMINDLogicConfig, MAKEMINDMarketplace, type MAKEMINDMarketplaceConfig, MAKEMINDMessaging, type MAKEMINDMessagingConfig, MAKEMINDSearch, type MAKEMINDSearchConfig, MAKEMINDSettlement, type MAKEMINDSettlementConfig, MAKEMINDStorage, type MAKEMINDStorageConfig, MAKEMINDTenant, type MAKEMINDTenantConfig, type Notification, type OrderBy, type PlatformErrorDetails, type QueryCondition, type QueryOptions, type QueryResult, type SendMessageOptions, type SnapshotCallback, type Tenant, type TenantClaims, type TenantMember, type Unsubscribe, type UpdateOptions, type UploadOptions, type UploadResult, type UsageEventOptions, type UsageStats, type WorkflowTransitionOptions, type Workspace, getMAKEMIND, initializeMAKEMIND, mountExpertChat };
+export { ApiClient, type ApiClientConfig, type ApiRequestOptions, type AuthStateCallback, type AuthUser, type BillingSummary, type CollectionSnapshotCallback, type ConsultResult, type ConsultationConclusion, type CreateOptions, type DeleteOptions, type DocumentResult, ErrorCodes, type ExpertAccess, ExpertChat, type ExpertChatWidget, type ExpertChatWidgetOptions, type ExpertConsultation, ExpertDoorError, type ExpertSession, type ExpertTurn, type FileMetadata, type FlowListItem, type GetOptions, type Invoice, type ListFilesOptions, type ListFilesResult, type ListFlowsParams, type ListFlowsResult, type LogicCallResult, MAKEMINDAI, type MAKEMINDAIConfig, MAKEMINDApps, type MAKEMINDAppsConfig, MAKEMINDAuth, type MAKEMINDAuthConfig, MAKEMINDClient, type MAKEMINDClientConfig, type MAKEMINDConfig, MAKEMINDData, type MAKEMINDDataConfig, MAKEMINDError, MAKEMINDExperts, type MAKEMINDExpertsConfig, MAKEMINDLogic, type MAKEMINDLogicConfig, MAKEMINDMarketplace, type MAKEMINDMarketplaceConfig, MAKEMINDMessaging, type MAKEMINDMessagingConfig, MAKEMINDSearch, type MAKEMINDSearchConfig, MAKEMINDSettlement, type MAKEMINDSettlementConfig, MAKEMINDStorage, type MAKEMINDStorageConfig, MAKEMINDTenant, type MAKEMINDTenantConfig, type Notification, type OcrLine, type OcrPage, type OcrResult, type OrderBy, type PlatformErrorDetails, type QueryCondition, type QueryOptions, type QueryResult, type SendMessageOptions, type SnapshotCallback, type Tenant, type TenantClaims, type TenantMember, type Unsubscribe, type UpdateOptions, type UploadOptions, type UploadResult, type UsageEventOptions, type UsageStats, type WorkflowTransitionOptions, type Workspace, getMAKEMIND, initializeMAKEMIND, mountExpertChat };