@dotbots-boutique/server-sdk 0.4.0 → 0.5.1

package/README.md

@@ -16,13 +16,13 @@ For user-facing interactions in the browser, use the frontend SDK (`@dotbots-bou
 ## Installation
 
 ```bash
-npm install @dotbots-boutique/server-sdk
+npm install @dotbots-boutique/server-sdk@0.4.0
 ```
 
 Or in Deno:
 
 ```typescript
-import { DotBotsBackend } from 'npm:@dotbots-boutique/server-sdk';
+import { DotBotsBackend } from 'npm:@dotbots-boutique/server-sdk@0.4.0';
 ```
 
 ## Environment variables
@@ -32,8 +32,7 @@ These are injected automatically by the DotBots platform — no manual configura
 ```
 DOTBOTS_APP_ID=uuid
 DOTBOTS_APP_SECRET=...
-PLATFORM_API_URL=https://api.dotbots.ai
-DOTBOTS_PROXY_URL=https://proxy.dotbots.ai
+DOTBOTS_API_URL=https://api.dotbots.boutique
 ENVIRONMENT=test|prod
 ```
 
@@ -42,12 +41,12 @@ ENVIRONMENT=test|prod
 Initialise once at app startup, before handling any requests:
 
 ```typescript
-import { DotBotsBackend } from 'npm:@dotbots-boutique/server-sdk';
+import { DotBotsBackend } from 'npm:@dotbots-boutique/server-sdk@0.4.0';
 
 const dotbots = new DotBotsBackend({
   appId: Deno.env.get('DOTBOTS_APP_ID')!,
   appSecret: Deno.env.get('DOTBOTS_APP_SECRET')!,
-  apiUrl: Deno.env.get('PLATFORM_API_URL') ?? 'https://api.dotbots.ai',
+  apiUrl: Deno.env.get('DOTBOTS_API_URL') ?? 'https://api.dotbots.boutique',
   environment: Deno.env.get('ENVIRONMENT') ?? 'prod'
 });
 
@@ -55,7 +54,7 @@ const dotbots = new DotBotsBackend({
 await dotbots.initialize();
 ```
 
-`initialize()` must be called before any other methods. If `DOTBOTS_PROXY_URL` is set, the proxy URL is used directly. Otherwise it fetches the proxy URL from the platform.
+`initialize()` fetches the proxy URL from the platform. It must complete before any AI calls, payments or user lookups are made.
 
 ## AI calls
 
@@ -103,16 +102,17 @@ await dotbots.aiStream(
 The `paidBy` value is configured per feature in the platform — default is `org`. Your code only needs to provide `orgId` when the feature charges the organisation:
 
 ```typescript
-// Feature paidBy = 'org' (default) — provide orgId
+// orgId is optional — SDK sends default org from app secret context
+await dotbots.charge('data-export', { quantity: 1 });
+
+// Explicitly provide orgId when charging a specific org
 await dotbots.charge('data-export', {
   orgId: user.orgId,
   quantity: 1
 });
 
 // Feature paidBy = 'app' — no orgId needed
-await dotbots.charge('internal-job', {
-  quantity: 1
-});
+await dotbots.charge('internal-job');
 ```
 
 ## Getting user info
@@ -125,7 +125,7 @@ console.log(user.name, user.orgId, user.roles);
 ## Error handling
 
 ```typescript
-import { DotBotsBackend, DotBotsBackendError } from 'npm:@dotbots-boutique/server-sdk';
+import { DotBotsBackend, DotBotsBackendError } from 'npm:@dotbots-boutique/server-sdk@0.4.0';
 
 try {
   const response = await dotbots.ai('generate-text', { messages, orgId });
@@ -150,6 +150,30 @@ try {
 }
 ```
 
+## Sending notifications
+
+Send a notification to a user. The notification type (email, SMS, platform), templates and placeholders are configured in the DotBots platform — your code only provides the parameters.
+
+```typescript
+await dotbots.sendNotification({
+  userExternalId: user.id,
+  userOrganisationExternalId: user.orgId,
+  code: 'invoice.created',      // as defined in the platform
+  language: 'nl',               // optional
+  parameters: {                 // optional — key-values for {{placeholders}}
+    invoiceNr: 'INV-42',
+    amount: '99,50'
+  },
+  important: false              // optional — marks as important
+});
+```
+
+Use `code` to identify the notification — it is the recommended approach. In the platform admin you can copy a ready-made example payload per notification with the correct `code` and parameter keys already filled in.
+
+**Always call this server-to-server** — the app secret must never appear in the browser.
+
+---
+
 ## Error codes
 
 | Code | Description |
@@ -161,6 +185,8 @@ try {
 | `CHARGE_FAILED` | Payment failed |
 | `USER_NOT_FOUND` | User not found |
 | `UNAUTHORIZED` | Invalid app secret |
+| `NOTIFICATION_NOT_FOUND` | Notification code does not belong to this app |
+| `NO_TEMPLATE_CONFIGURED` | No template configured for this notification |
 
 ## Frontend SDK vs Backend SDK
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AiResponse, BackendAiRequest, DotBotsBackendConfig, DotBotsUser } from './types';
+import type { AiResponse, BackendAiRequest, DotBotsBackendConfig, DotBotsUser, SendNotificationRequest, SendNotificationResponse } from './types';
 export declare class DotBotsBackend {
     private appId;
     private appSecret;
@@ -9,7 +9,7 @@ export declare class DotBotsBackend {
     initialize(): Promise<void>;
     ai(feature: string, request: BackendAiRequest, onDelta?: (delta: string) => void): Promise<AiResponse>;
     aiStream(feature: string, request: BackendAiRequest, onDelta: (delta: string) => void, onDone?: (response: AiResponse) => void): Promise<void>;
-    charge(featureCode: string, options: {
+    charge(featureCode: string, options?: {
         paidBy?: 'org' | 'app';
         orgId?: string;
         quantity?: number;
@@ -18,6 +18,7 @@ export declare class DotBotsBackend {
         amount: bigint;
     }>;
     getUser(userId: string): Promise<DotBotsUser>;
+    sendNotification(request: SendNotificationRequest): Promise<SendNotificationResponse>;
     private baseHeaders;
     private getProxyUrl;
 }

package/dist/client.js

@@ -38,29 +38,9 @@ class DotBotsBackend {
         }));
     }
     async ai(feature, request, onDelta) {
-        if (onDelta !== undefined) {
-            return new Promise((resolve, reject) => {
-                this.aiStream(feature, request, onDelta, resolve).catch(reject);
-            });
-        }
-        const response = await fetch(`${this.getProxyUrl()}/ai/call`, {
-            method: 'POST',
-            headers: this.baseHeaders(),
-            body: JSON.stringify({
-                feature,
-                messages: request.messages,
-                tools: request.tools,
-                stream: false,
-                maxTokens: request.maxTokens,
-                paidBy: request.paidBy,
-                orgId: request.orgId,
-            }),
+        return new Promise((resolve, reject) => {
+            this.aiStream(feature, request, onDelta ?? (() => { }), resolve).catch(reject);
         });
-        if (!response.ok) {
-            const body = (await response.json().catch(() => ({})));
-            throw new errors_1.DotBotsBackendError(body.error ?? 'AI_CALL_FAILED', response.status);
-        }
-        return (await response.json());
     }
     async aiStream(feature, request, onDelta, onDone) {
         const response = await fetch(`${this.getProxyUrl()}/ai/call`, {
@@ -98,10 +78,13 @@ class DotBotsBackend {
                     onDelta(data.delta);
                 else if (data.type === 'done')
                     onDone?.(data);
+                else if (data.type === 'error') {
+                    throw new errors_1.DotBotsBackendError(data.error ?? 'AI_CALL_FAILED', 500);
+                }
             }
         }
     }
-    async charge(featureCode, options) {
+    async charge(featureCode, options = {}) {
         const response = await fetch(`${this.getProxyUrl()}/payments/charge`, {
             method: 'POST',
             headers: this.baseHeaders(),
@@ -125,6 +108,18 @@ class DotBotsBackend {
         }
         return (await response.json());
     }
+    async sendNotification(request) {
+        const response = await fetch(`${this.getProxyUrl()}/notifications/send`, {
+            method: 'POST',
+            headers: this.baseHeaders(),
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new errors_1.DotBotsBackendError(body.error ?? 'NOTIFICATION_FAILED', response.status);
+        }
+        return (await response.json());
+    }
     baseHeaders() {
         return {
             'Content-Type': 'application/json',

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { DotBotsBackend } from './client';
 export { DotBotsBackendError } from './errors';
-export type { AiImage, AiMessage, AiResponse, AiTool, AiToolCall, AiToolParameter, BackendAiRequest, DotBotsBackendConfig, DotBotsUser, } from './types';
+export type { AiImage, AiMessage, AiResponse, AiTool, AiToolCall, AiToolParameter, BackendAiRequest, DotBotsBackendConfig, DotBotsUser, SendNotificationRequest, SendNotificationResponse, } from './types';
 export { AppSecretsStore } from './proxy/app-secrets';
 export { handleAiCall, handleCharge, handleGetUser, handleInternalAppSecrets, resolveAuth, } from './proxy/handlers';
 export type { AuthResult, CryptoHelpers, DbClient, FeatureConfig, JwtPayload, UserRecord, } from './proxy/types';

package/dist/types.d.ts

@@ -65,3 +65,17 @@ export interface DotBotsUser {
     email?: string;
     name?: string;
 }
+export interface SendNotificationRequest {
+    userExternalId: string;
+    userOrganisationExternalId: string;
+    code?: string;
+    notificationDescriptionId?: string;
+    language?: string;
+    parameters?: Record<string, string>;
+    important?: boolean;
+}
+export interface SendNotificationResponse {
+    id: string;
+    type: string;
+    status: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotbots-boutique/server-sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "DotBots Backend SDK — server-side AI calls, payments, and user lookups via the DotBots proxy",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",