backprompter-server-sdk 0.1.1 → 0.1.3

package/README.md

@@ -28,6 +28,124 @@ const result = await bp.run({
 console.log(result.response);
 ```
 
+## Attachments
+
+`run()` takes `fileInputs` and `urlInputs`, and which key you use inside
+`fileInputs` decides how an attachment is sent:
+
+| Key | Sent as |
+|---|---|
+| `url`, `dataUrl`, `base64` | image |
+| `file_url`, `file_data` | document |
+
+The backend infers the real type where it can — an explicit `mimeType`, the
+data-URL prefix, the file extension, or the leading bytes of base64 — and falls
+back to the key only when the type cannot be determined.
+
+```js
+await bp.run({
+  agentId: 'analyst',
+  userPrompt: 'What are the Q3 totals?',
+  fileInputs: [
+    { file_url: 'https://example.com/q3.pdf', filename: 'q3.pdf' },   // document
+    { url: 'https://example.com/chart.png' }                          // image
+  ]
+});
+```
+
+Document support is per model: OpenAI models accept spreadsheets, while
+Anthropic accepts PDF only and rejects other types outright. Pick a model that
+handles what you send.
+
+## Use your own login
+
+Your app can keep its own login. Backprompter never has to see a password.
+
+Your backend exchanges your user id for a session token. Your frontend signs in
+with that token. The frontend then reaches every browser SDK function, including
+`saveData`, `search`, file handling and voice.
+
+```js
+// your backend, behind your own session check
+app.post('/api/bp-token', requireMyAuth, async (req, res) => {
+  const { customToken } = await bp.createUserToken({
+    externalId: req.user.id,        // your own user id
+    email: req.user.email           // a label for your dashboard
+  });
+  res.json({ customToken });
+});
+```
+
+```js
+// your frontend, after your own login succeeds
+const { customToken } = await fetch('/api/bp-token').then((r) => r.json());
+await Backprompter.signInWithCustomToken(customToken);
+```
+
+Backprompter derives a storage id from your tenant id and your external id. The
+same external id always returns to the same data. You cannot choose the id.
+
+Keep the API key on your server. Only the token reaches the browser. A token is
+valid for one user of one app.
+
+## End-user data from your backend
+
+You can also skip the browser session and do everything from your server. Call
+`forUser()` with your own user id.
+
+```js
+const user = bp.forUser('u_8821');
+
+await user.saveData('preferences', { theme: 'dark' });
+const prefs = await user.getData('preferences');
+
+await user.saveConversation(conversationId, messages, { title: 'Support' });
+const list = await user.listConversations();
+
+await user.storeArtifacts([{ name: 'notes.md', content: text }]);
+const hits = await user.search('last quarter revenue', { k: 5 });
+```
+
+Every call reads and writes that person's data only. The API key decides the app.
+The external id decides the person.
+
+The handle covers stored data. Agent calls stay on `bp.run()`, because a run is
+not bound to a person. Pass what the agent should know about them in
+`profileString`.
+
+```js
+const profile = await user.getData('profile');
+const result = await bp.run({
+  agentId: 'analyst',
+  userPrompt: 'What changed?',
+  profileString: JSON.stringify(profile.data)
+});
+```
+
+### API key scopes
+
+New API keys carry three scopes: `run:public`, `enduser:data`, and
+`identity:exchange`. Keys generated before these features existed carry only
+`run:public`. To use `forUser()` or `createUserToken()`, generate a new key.
+
+## Payments
+
+An API key never triggers the Backprompter payment gate. Your backend is your
+own integration, so you decide what a person may do.
+
+Read the entitlement yourself when you want to enforce payment:
+
+```js
+const { active, paymentRequired } = await bp.forUser('u_8821').getEntitlements();
+if (paymentRequired && !active) return res.status(402).json({ error: 'Subscribe first' });
+```
+
+The gate applies only to end users signed in with a Backprompter token. That
+includes users who signed in with a custom token from `createUserToken()`.
+
+If you collect money outside Backprompter, leave the Backprompter payment
+settings empty. No gate then applies to anyone.
+
 ## Notes
 
 - Requires Node.js 18+ (uses built-in fetch).

package/index.js

@@ -65,7 +65,12 @@ export default class BackprompterServer {
     baseText,
     ragCharBudget,
     tenantId,
-    apiKey
+    apiKey,
+    // Streaming: the Promise still resolves with the complete result; these
+    // callbacks see the answer as it is written. See _streamRun.
+    stream,
+    onDelta,
+    onStatus
   } = {}) {
     const resolvedApiKey = String(apiKey || this._apiKey || '').trim();
     if (!resolvedApiKey) throw new Error('BackprompterServer: apiKey is required.');
@@ -88,12 +93,162 @@ export default class BackprompterServer {
     if (baseText !== undefined) body.base_text = baseText;
     if (ragCharBudget !== undefined) body.rag_char_budget = ragCharBudget;
 
+    if (stream) return this._streamRun(resolvedApiKey, body, { onDelta, onStatus });
     return this._apiFetchWithApiKey('/public/run', resolvedApiKey, {
       method: 'POST',
       body: JSON.stringify(body)
     });
   }
 
+  // POST /public/run with "stream": true and read the server-sent events.
+  // Resolves with the same object as a non-streamed run (the `done` event).
+  //   onDelta(text, fullTextSoFar) — each piece of the answer
+  //   onStatus(event)              — { type: 'meta', agentId, artifactType, streaming }
+  //                                  { type: 'status', stage: 'routing' | 'retrieving' | 'tool', name? }
+  //                                  { type: 'reset' }  (discard the text so far)
+  // A plain JSON reply (a refusal, or a backend without streaming) is handled
+  // like an ordinary run.
+  async _streamRun(apiKey, body, { onDelta, onStatus } = {}) {
+    assertFetchAvailable();
+    const response = await fetch(`${this._backendUrl}/public/run`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Accept': 'text/event-stream', 'x-bp-api-key': apiKey },
+      body: JSON.stringify({ ...body, stream: true })
+    });
+    const type = response.headers.get('content-type') || '';
+    if (!type.startsWith('text/event-stream') || !response.body) {
+      const payload = await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error(getErrorMessage(response.status, payload));
+      return payload;
+    }
+
+    const call = (fn, ...args) => {
+      if (typeof fn !== 'function') return;
+      try { fn(...args); } catch (e) { console.error('BackprompterServer stream callback error:', e); }
+    };
+    let text = '';
+    let result = null;
+    let failure = null;
+    const handle = (name, raw) => {
+      let data;
+      try { data = JSON.parse(raw); } catch (_) { return; }
+      if (name === 'delta') {
+        const piece = String((data && data.text) || '');
+        if (!piece) return;
+        text += piece;
+        call(onDelta, piece, text);
+      } else if (name === 'reset') {
+        text = '';
+        call(onStatus, { type: 'reset' });
+      } else if (name === 'meta' || name === 'status') {
+        call(onStatus, { type: name, ...data });
+      } else if (name === 'done') {
+        result = data;
+      } else if (name === 'error') {
+        failure = new Error(getErrorMessage(data && data.status, data));
+      }
+    };
+
+    let buffer = '';
+    let eventName = '';
+    let dataLines = [];
+    const line = (l) => {
+      if (l.endsWith('\r')) l = l.slice(0, -1);
+      if (l === '') {
+        if (dataLines.length) handle(eventName || 'message', dataLines.join('\n'));
+        eventName = '';
+        dataLines = [];
+      } else if (l.startsWith('event:')) {
+        eventName = l.slice(6).trim();
+      } else if (l.startsWith('data:')) {
+        dataLines.push(l.slice(5).replace(/^ /, ''));
+      }
+    };
+    const decoder = new TextDecoder();
+    for await (const chunk of response.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+      let nl;
+      while ((nl = buffer.indexOf('\n')) !== -1) {
+        line(buffer.slice(0, nl));
+        buffer = buffer.slice(nl + 1);
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer) line(buffer);
+    line('');
+
+    if (failure) throw failure;
+    if (!result) throw new Error('BackprompterServer: the reply stream ended before the answer was complete.');
+    return result;
+  }
+
+  // ── Identity ────────────────────────────────────────────────────────────
+
+  /**
+   * Exchange your own user id for a Backprompter session token.
+   *
+   * Call this from your backend after your own login succeeds. Send the token
+   * to your frontend and pass it to Backprompter.signInWithCustomToken(token).
+   * Your frontend then reaches every browser SDK function. Your API key stays
+   * on your server.
+   *
+   * The API key must carry the identity:exchange scope.
+   *
+   * @param {object} opts
+   * @param {string} opts.externalId  — your own user id, required
+   * @param {string} [opts.email]     — label only, shown in your dashboard
+   * @param {string} [opts.displayName]
+   * @param {object} [opts.claims]    — extra claims. Reserved names are dropped.
+   * @returns {Promise<{ customToken: string, uid: string, tenantId: string }>}
+   */
+  async createUserToken({ externalId, email, displayName, claims, tenantId, apiKey } = {}) {
+    const resolvedExternalId = String(externalId || '').trim();
+    if (!resolvedExternalId) throw new Error('BackprompterServer: externalId is required.');
+
+    const body = { externalId: resolvedExternalId };
+    if (email) body.email = String(email).trim();
+    if (displayName) body.displayName = String(displayName).trim();
+    if (claims && typeof claims === 'object') body.claims = claims;
+
+    return this._endUserFetch('exchange', {
+      method: 'POST',
+      body: JSON.stringify(body)
+    }, { tenantId, apiKey });
+  }
+
+  // ── End-user data ───────────────────────────────────────────────────────
+
+  /**
+   * A handle that acts for one of your users. Every call on it reads and writes
+   * that person's own data, and nobody else's.
+   *
+   * @param {string} externalId — your own user id
+   * @returns {BackprompterUser}
+   */
+  forUser(externalId) {
+    const resolved = String(externalId || '').trim();
+    if (!resolved) throw new Error('BackprompterServer: externalId is required.');
+    return new BackprompterUser(this, resolved);
+  }
+
+  _requireTenantId(tenantId) {
+    const resolved = String(tenantId || this._tenantId || '').trim();
+    if (!resolved) throw new Error('BackprompterServer: tenantId is required.');
+    return resolved;
+  }
+
+  async _endUserFetch(subPath, options = {}, { tenantId, apiKey, externalId } = {}) {
+    const resolvedApiKey = String(apiKey || this._apiKey || '').trim();
+    if (!resolvedApiKey) throw new Error('BackprompterServer: apiKey is required.');
+    const resolvedTenantId = this._requireTenantId(tenantId);
+
+    const headers = { ...(options.headers || {}) };
+    if (externalId) headers['x-bp-end-user'] = String(externalId);
+
+    const path = `/api/app/${encodeURIComponent(resolvedTenantId)}/enduser/${subPath}`;
+    return this._apiFetchWithApiKey(path, resolvedApiKey, { ...options, headers });
+  }
+
   async _apiFetchWithApiKey(path, apiKey, options = {}) {
     assertFetchAvailable();
 
@@ -117,3 +272,118 @@ export default class BackprompterServer {
     return payload;
   }
 }
+
+/**
+ * Acts for one of your users. Create it with backprompterServer.forUser(id).
+ *
+ * The API key decides which app the calls reach. The external id decides which
+ * person inside that app. Backprompter derives a stable storage id from the two,
+ * so the same external id always returns to the same data.
+ */
+export class BackprompterUser {
+  constructor(server, externalId) {
+    this._server = server;
+    this._externalId = externalId;
+  }
+
+  get externalId() {
+    return this._externalId;
+  }
+
+  _fetch(subPath, options = {}) {
+    return this._server._endUserFetch(subPath, options, { externalId: this._externalId });
+  }
+
+  /** Mint a browser session token for this user. */
+  createToken(opts = {}) {
+    return this._server.createUserToken({ ...opts, externalId: this._externalId });
+  }
+
+  // ── Custom data ───────────────────────────────────────────────────────
+
+  saveData(docId, data) {
+    return this._fetch(`data/${encodeURIComponent(docId)}`, {
+      method: 'POST',
+      body: JSON.stringify({ data })
+    });
+  }
+
+  getData(docId) {
+    return this._fetch(`data/${encodeURIComponent(docId)}`);
+  }
+
+  deleteData(docId) {
+    return this._fetch(`data/${encodeURIComponent(docId)}`, { method: 'DELETE' });
+  }
+
+  // ── Conversations ─────────────────────────────────────────────────────
+
+  saveConversation(conversationId, messages, metadata = {}) {
+    return this._fetch(`conversations/${encodeURIComponent(conversationId)}`, {
+      method: 'POST',
+      body: JSON.stringify({ messages, metadata })
+    });
+  }
+
+  listConversations() {
+    return this._fetch('conversations');
+  }
+
+  getConversation(conversationId) {
+    return this._fetch(`conversations/${encodeURIComponent(conversationId)}`);
+  }
+
+  deleteConversation(conversationId) {
+    return this._fetch(`conversations/${encodeURIComponent(conversationId)}`, { method: 'DELETE' });
+  }
+
+  // ── Artifacts ─────────────────────────────────────────────────────────
+
+  storeArtifacts(files) {
+    return this._fetch('artifacts', {
+      method: 'POST',
+      body: JSON.stringify({ files })
+    });
+  }
+
+  listArtifacts() {
+    return this._fetch('artifacts');
+  }
+
+  getArtifact(docId) {
+    return this._fetch(`artifacts/${encodeURIComponent(docId)}`);
+  }
+
+  deleteArtifact(docId) {
+    return this._fetch(`artifacts/${encodeURIComponent(docId)}`, { method: 'DELETE' });
+  }
+
+  // ── Search ────────────────────────────────────────────────────────────
+
+  search(query, { searchIn = ['conversations', 'artifacts'], k = 5 } = {}) {
+    return this._fetch('search', {
+      method: 'POST',
+      body: JSON.stringify({ query, searchIn, k })
+    });
+  }
+
+  // ── Payments ──────────────────────────────────────────────────────────
+
+  getEntitlements() {
+    return this._fetch('entitlements');
+  }
+
+  createCheckoutSession({ successUrl, cancelUrl } = {}) {
+    return this._fetch('checkout-session', {
+      method: 'POST',
+      body: JSON.stringify({ successUrl, cancelUrl })
+    });
+  }
+
+  createBillingPortalSession({ returnUrl } = {}) {
+    return this._fetch('billing-portal', {
+      method: 'POST',
+      body: JSON.stringify({ returnUrl })
+    });
+  }
+}

package/package.json

@@ -1,23 +1,23 @@
-{
-  "name": "backprompter-server-sdk",
-  "version": "0.1.1",
-  "description": "Backprompter server-side SDK for Node.js backends",
-  "type": "module",
-  "main": "index.js",
-  "exports": {
-    ".": "./index.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "backprompter",
-    "sdk",
-    "server",
-    "node"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "backprompter-server-sdk",
+  "version": "0.1.3",
+  "description": "Backprompter server-side SDK for Node.js backends",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "backprompter",
+    "sdk",
+    "server",
+    "node"
+  ],
+  "license": "MIT"
+}