flowstack-sdk 0.2.1 → 0.2.3

package/README.md

@@ -1,5 +1,10 @@
 # Flowstack SDK
 
+[![npm version](https://img.shields.io/npm/v/flowstack-sdk.svg)](https://www.npmjs.com/package/flowstack-sdk)
+[![npm downloads/week](https://img.shields.io/npm/dw/flowstack-sdk.svg)](https://www.npmjs.com/package/flowstack-sdk)
+[![npm total downloads](https://img.shields.io/npm/dt/flowstack-sdk.svg)](https://www.npmjs.com/package/flowstack-sdk)
+[![license](https://img.shields.io/npm/l/flowstack-sdk.svg)](https://www.npmjs.com/package/flowstack-sdk)
+
 Complete Backend-as-a-Service SDK for AI-powered applications. Build full-stack AI apps with authentication, workspace management, dataset handling, AI agent integration, published sites, and wallet-based payments — all in one package.
 
 ```bash
@@ -1553,6 +1558,83 @@ Return value:
 
 ---
 
+## Private Messaging (DMs)
+
+Built-app users can exchange private, one-to-one messages. The DM store is **server-owned and ACL'd**: the backend pins `from` to the caller's JWT identity, only ever returns threads the caller participates in, and gates sends on a **mutually-consented (open) thread** — neither party ever learns the other's contact details.
+
+Private messaging is a **built-app capability**. It requires an `appScope` on the `FlowstackProvider` config; in a Casino personal session the backend returns 403. All symbols below ship in **0.2.2+**.
+
+> **Security:** message bodies are UNTRUSTED user input. Render them as plain text or sanitized markdown — never as raw HTML (no `dangerouslySetInnerHTML`). If a body is ever passed to an agent, treat it as data, not instructions.
+
+### useThreads — list a user's threads
+
+```tsx
+import { useThreads } from 'flowstack-sdk';
+
+const { threads, isLoading, error, refresh, openThread } = useThreads({
+  refreshInterval: 5000, // optional auto-poll (ms); off by default
+});
+
+// Each thread: { pair_key, with_user_key, status: 'pending' | 'open', last_message, unread_count, updated_at }
+threads.map((t) => <ThreadRow key={t.pair_key} counterpart={t.with_user_key} unread={t.unread_count} />);
+
+// Consent to open a thread — becomes sendable only once BOTH parties consent.
+const status = await openThread(otherUserKey); // 'pending' | 'open' | null
+```
+
+### useMessages — read + send within one thread
+
+```tsx
+import { useMessages } from 'flowstack-sdk';
+
+const { messages, send, isLoading, error, refresh } = useMessages(counterpartUserKey, {
+  limit: 50,           // default 50, max 200
+  refreshInterval: 4000,
+});
+
+await send('hey there'); // 403 / error if the thread is not yet mutually open
+messages.map((m) => <Bubble key={m.message_id} mine={m.from === myKey}>{m.body}</Bubble>);
+```
+
+### Client functions (non-React)
+
+All take `(credentials, …, config)` where `config` must carry `appScope`. Each returns an `ApiResponse<T>` (`{ ok, data, error }`), except `dmPairKey` which is a pure helper.
+
+```ts
+import {
+  listThreads,      // (creds, config) → { threads: DmThread[]; count }
+  listMessages,     // (creds, withUserKey, { limit?, before? }, config) → { messages: DmMessage[]; count }
+  sendMessage,      // (creds, toUserKey, body, config) → { message_id, created_at }  — 403 unless thread open
+  openThread,       // (creds, withUserKey, config) → { pair_key, status }  — record caller's consent
+  markMessageRead,  // (creds, messageId, config) → { message_id, read }  — recipient only
+  dmPairKey,        // (a, b) → string  — deterministic, order-independent thread key (sorted, '::'-joined)
+} from 'flowstack-sdk';
+```
+
+**Types:**
+
+```ts
+interface DmMessage {
+  message_id: string;
+  from: string;
+  to: string;
+  body: string;        // UNTRUSTED — render as text, never raw HTML
+  created_at: string;
+  read_at: string | null;
+}
+
+interface DmThread {
+  pair_key: string;
+  with_user_key: string;
+  status: 'pending' | 'open';
+  last_message: DmMessage | null;
+  unread_count: number;
+  updated_at: string | null;
+}
+```
+
+---
+
 ## Components
 
 ### Pre-built Page Components

package/dist/api/index.d.mts

@@ -1 +1 @@
-export { bM as CACHE_TTL, c7 as CreateSiteParams, N as FlowstackClientConfig, c8 as RedisConfig, bL as RequestOptions, bD as addPiiAllowlistTerm, bk as addSiteFile, be as checkAdminPermissions, aZ as createDataSource, bj as createSite, aN as createWorkspace, c4 as deleteCached, a$ as deleteDataSource, aS as deleteDataset, bv as deleteDocuments, bm as deleteSite, bp as deleteSiteVersion, b9 as deleteUser, bJ as deleteUserCollection, b0 as executeQuery, b1 as executeQueryWithConfig, bK as exportUserCollection, aL as flowstackFetch, c2 as getCached, bQ as getCachedDatasets, bW as getCachedReports, b$ as getCachedSites, bT as getCachedVisualizations, bN as getCachedWorkspaces, bf as getConversationHistory, aQ as getDataset, aR as getDatasetPreview, aX as getModel, bC as getPiiAllowlist, bz as getPiiSettings, bi as getSite, bn as getSiteVersions, b7 as getUser, bc as getUserActivity, bH as getUserCollectionDocuments, bI as getUserCollectionSchema, bG as getUserCollections, bF as getUserDataOverview, bd as getUserStats, aO as getWorkspace, b5 as googleLogin, by as importFromGitHub, bt as insertDocuments, b_ as invalidateAllUserCache, bS as invalidateDatasetsCache, bY as invalidateReportsCache, c1 as invalidateSitesCache, bV as invalidateVisualizationsCache, bZ as invalidateWorkspaceArtifacts, bP as invalidateWorkspacesCache, bw as invokeTool, bg as listAgents, aY as listDataSources, aP as listDatasets, bx as listGitHubRepos, aV as listModels, aU as listReports, aW as listScripts, bh as listSites, b6 as listUsers, aT as listVisualizations, aM as listWorkspaces, b3 as login, bB as previewPiiMasking, bo as promoteSiteVersion, bl as publishStagedSite, bs as publishToGitHub, c5 as queryCollection, bb as reactivateUser, b4 as register, bE as removePiiAllowlistTerm, br as removeSiteAlias, c3 as setCached, bR as setCachedDatasets, bX as setCachedReports, c0 as setCachedSites, bU as setCachedVisualizations, bO as setCachedWorkspaces, bq as setSiteAlias, ba as suspendUser, a_ as testDataSource, bu as updateDocuments, bA as updatePiiSettings, b8 as updateUser, c6 as uploadDocument, b2 as uploadFile } from '../index-BkACA2ls.mjs';
+export { bU as CACHE_TTL, cf as CreateSiteParams, o as DmMessage, D as DmThread, R as FlowstackClientConfig, cg as RedisConfig, bT as RequestOptions, bL as addPiiAllowlistTerm, bm as addSiteFile, bg as checkAdminPermissions, a$ as createDataSource, bl as createSite, aP as createWorkspace, cc as deleteCached, b1 as deleteDataSource, aU as deleteDataset, bx as deleteDocuments, bo as deleteSite, br as deleteSiteVersion, bb as deleteUser, bR as deleteUserCollection, bD as dmPairKey, b2 as executeQuery, b3 as executeQueryWithConfig, bS as exportUserCollection, aN as flowstackFetch, ca as getCached, bY as getCachedDatasets, c2 as getCachedReports, c7 as getCachedSites, b$ as getCachedVisualizations, bV as getCachedWorkspaces, bh as getConversationHistory, aS as getDataset, aT as getDatasetPreview, aZ as getModel, bK as getPiiAllowlist, bH as getPiiSettings, bk as getSite, bp as getSiteVersions, b9 as getUser, be as getUserActivity, bP as getUserCollectionDocuments, bQ as getUserCollectionSchema, bO as getUserCollections, bN as getUserDataOverview, bf as getUserStats, aQ as getWorkspace, b7 as googleLogin, bG as importFromGitHub, bv as insertDocuments, c6 as invalidateAllUserCache, b_ as invalidateDatasetsCache, c4 as invalidateReportsCache, c9 as invalidateSitesCache, c1 as invalidateVisualizationsCache, c5 as invalidateWorkspaceArtifacts, bX as invalidateWorkspacesCache, bE as invokeTool, bi as listAgents, a_ as listDataSources, aR as listDatasets, bF as listGitHubRepos, bz as listMessages, aX as listModels, aW as listReports, aY as listScripts, bj as listSites, by as listThreads, b8 as listUsers, aV as listVisualizations, aO as listWorkspaces, b5 as login, bC as markMessageRead, bB as openThread, bJ as previewPiiMasking, bq as promoteSiteVersion, bn as publishStagedSite, bu as publishToGitHub, cd as queryCollection, bd as reactivateUser, b6 as register, bM as removePiiAllowlistTerm, bt as removeSiteAlias, bA as sendMessage, cb as setCached, bZ as setCachedDatasets, c3 as setCachedReports, c8 as setCachedSites, c0 as setCachedVisualizations, bW as setCachedWorkspaces, bs as setSiteAlias, bc as suspendUser, b0 as testDataSource, bw as updateDocuments, bI as updatePiiSettings, ba as updateUser, ce as uploadDocument, b4 as uploadFile } from '../index-CUyJ5c2d.mjs';

package/dist/api/index.d.ts

@@ -1 +1 @@
-export { bM as CACHE_TTL, c7 as CreateSiteParams, N as FlowstackClientConfig, c8 as RedisConfig, bL as RequestOptions, bD as addPiiAllowlistTerm, bk as addSiteFile, be as checkAdminPermissions, aZ as createDataSource, bj as createSite, aN as createWorkspace, c4 as deleteCached, a$ as deleteDataSource, aS as deleteDataset, bv as deleteDocuments, bm as deleteSite, bp as deleteSiteVersion, b9 as deleteUser, bJ as deleteUserCollection, b0 as executeQuery, b1 as executeQueryWithConfig, bK as exportUserCollection, aL as flowstackFetch, c2 as getCached, bQ as getCachedDatasets, bW as getCachedReports, b$ as getCachedSites, bT as getCachedVisualizations, bN as getCachedWorkspaces, bf as getConversationHistory, aQ as getDataset, aR as getDatasetPreview, aX as getModel, bC as getPiiAllowlist, bz as getPiiSettings, bi as getSite, bn as getSiteVersions, b7 as getUser, bc as getUserActivity, bH as getUserCollectionDocuments, bI as getUserCollectionSchema, bG as getUserCollections, bF as getUserDataOverview, bd as getUserStats, aO as getWorkspace, b5 as googleLogin, by as importFromGitHub, bt as insertDocuments, b_ as invalidateAllUserCache, bS as invalidateDatasetsCache, bY as invalidateReportsCache, c1 as invalidateSitesCache, bV as invalidateVisualizationsCache, bZ as invalidateWorkspaceArtifacts, bP as invalidateWorkspacesCache, bw as invokeTool, bg as listAgents, aY as listDataSources, aP as listDatasets, bx as listGitHubRepos, aV as listModels, aU as listReports, aW as listScripts, bh as listSites, b6 as listUsers, aT as listVisualizations, aM as listWorkspaces, b3 as login, bB as previewPiiMasking, bo as promoteSiteVersion, bl as publishStagedSite, bs as publishToGitHub, c5 as queryCollection, bb as reactivateUser, b4 as register, bE as removePiiAllowlistTerm, br as removeSiteAlias, c3 as setCached, bR as setCachedDatasets, bX as setCachedReports, c0 as setCachedSites, bU as setCachedVisualizations, bO as setCachedWorkspaces, bq as setSiteAlias, ba as suspendUser, a_ as testDataSource, bu as updateDocuments, bA as updatePiiSettings, b8 as updateUser, c6 as uploadDocument, b2 as uploadFile } from '../index-BkACA2ls.js';
+export { bU as CACHE_TTL, cf as CreateSiteParams, o as DmMessage, D as DmThread, R as FlowstackClientConfig, cg as RedisConfig, bT as RequestOptions, bL as addPiiAllowlistTerm, bm as addSiteFile, bg as checkAdminPermissions, a$ as createDataSource, bl as createSite, aP as createWorkspace, cc as deleteCached, b1 as deleteDataSource, aU as deleteDataset, bx as deleteDocuments, bo as deleteSite, br as deleteSiteVersion, bb as deleteUser, bR as deleteUserCollection, bD as dmPairKey, b2 as executeQuery, b3 as executeQueryWithConfig, bS as exportUserCollection, aN as flowstackFetch, ca as getCached, bY as getCachedDatasets, c2 as getCachedReports, c7 as getCachedSites, b$ as getCachedVisualizations, bV as getCachedWorkspaces, bh as getConversationHistory, aS as getDataset, aT as getDatasetPreview, aZ as getModel, bK as getPiiAllowlist, bH as getPiiSettings, bk as getSite, bp as getSiteVersions, b9 as getUser, be as getUserActivity, bP as getUserCollectionDocuments, bQ as getUserCollectionSchema, bO as getUserCollections, bN as getUserDataOverview, bf as getUserStats, aQ as getWorkspace, b7 as googleLogin, bG as importFromGitHub, bv as insertDocuments, c6 as invalidateAllUserCache, b_ as invalidateDatasetsCache, c4 as invalidateReportsCache, c9 as invalidateSitesCache, c1 as invalidateVisualizationsCache, c5 as invalidateWorkspaceArtifacts, bX as invalidateWorkspacesCache, bE as invokeTool, bi as listAgents, a_ as listDataSources, aR as listDatasets, bF as listGitHubRepos, bz as listMessages, aX as listModels, aW as listReports, aY as listScripts, bj as listSites, by as listThreads, b8 as listUsers, aV as listVisualizations, aO as listWorkspaces, b5 as login, bC as markMessageRead, bB as openThread, bJ as previewPiiMasking, bq as promoteSiteVersion, bn as publishStagedSite, bu as publishToGitHub, cd as queryCollection, bd as reactivateUser, b6 as register, bM as removePiiAllowlistTerm, bt as removeSiteAlias, bA as sendMessage, cb as setCached, bZ as setCachedDatasets, c3 as setCachedReports, c8 as setCachedSites, c0 as setCachedVisualizations, bW as setCachedWorkspaces, bs as setSiteAlias, bc as suspendUser, b0 as testDataSource, bw as updateDocuments, bI as updatePiiSettings, ba as updateUser, ce as uploadDocument, b4 as uploadFile } from '../index-CUyJ5c2d.js';

package/dist/api/index.js

@@ -264,7 +264,25 @@ async function executeQueryWithConfig(credentials, query, workspaceId, options,
     })
   });
   if (!response.ok) {
-    throw new Error(`Query failed: ${response.statusText}`);
+    let message = response.statusText || "request failed";
+    let code;
+    let body;
+    try {
+      body = await response.clone().json();
+      const payload = body && typeof body === "object" && "detail" in body && typeof body.detail === "object" ? body.detail : body;
+      if (payload && typeof payload === "object") {
+        code = payload.code;
+        message = payload.error || payload.message || payload.detail || message;
+      } else if (typeof payload === "string") {
+        message = payload;
+      }
+    } catch {
+    }
+    const err = new Error(`Query failed: ${message}`);
+    err.status = response.status;
+    err.code = code;
+    err.body = body;
+    throw err;
   }
   return response;
 }
@@ -332,6 +350,63 @@ async function deleteDocuments(credentials, collection, filter, config, layer) {
     config
   );
 }
+function dmPairKey(a, b) {
+  return [a, b].sort().join("::");
+}
+function requireAppScope(config) {
+  const scope = config?.appScope;
+  if (!scope) {
+    throw new Error("Private messaging requires an app scope (built-app context).");
+  }
+  return scope;
+}
+async function listThreads(credentials, config) {
+  const scope = requireAppScope(config);
+  return flowstackFetch(
+    `/apps/${encodeURIComponent(scope)}/threads`,
+    { credentials },
+    config
+  );
+}
+async function listMessages(credentials, withUserKey, options, config) {
+  const scope = requireAppScope(config);
+  const params = new URLSearchParams();
+  params.set("with", withUserKey);
+  if (options?.limit) params.set("limit", String(options.limit));
+  if (options?.before) params.set("before", options.before);
+  return flowstackFetch(
+    `/apps/${encodeURIComponent(scope)}/messages?${params.toString()}`,
+    { credentials },
+    config
+  );
+}
+async function sendMessage(credentials, toUserKey, body, config) {
+  const scope = requireAppScope(config);
+  return flowstackFetch(
+    `/apps/${encodeURIComponent(scope)}/messages`,
+    { method: "POST", credentials, body: { to_user_key: toUserKey, body } },
+    config
+  );
+}
+async function openThread(credentials, withUserKey, config) {
+  const scope = requireAppScope(config);
+  const me = credentials.userId;
+  if (!me) throw new Error("openThread requires an authenticated user.");
+  const pk = dmPairKey(me, withUserKey);
+  return flowstackFetch(
+    `/apps/${encodeURIComponent(scope)}/threads/${encodeURIComponent(pk)}/consent`,
+    { method: "POST", credentials },
+    config
+  );
+}
+async function markMessageRead(credentials, messageId, config) {
+  const scope = requireAppScope(config);
+  return flowstackFetch(
+    `/apps/${encodeURIComponent(scope)}/messages/${encodeURIComponent(messageId)}/read`,
+    { method: "POST", credentials },
+    config
+  );
+}
 async function invokeTool(credentials, agentName, toolName, kwargs = {}, config) {
   return flowstackFetch(
     "/tool/invoke",
@@ -989,6 +1064,7 @@ exports.deleteSite = deleteSite;
 exports.deleteSiteVersion = deleteSiteVersion;
 exports.deleteUser = deleteUser;
 exports.deleteUserCollection = deleteUserCollection;
+exports.dmPairKey = dmPairKey;
 exports.executeQuery = executeQuery;
 exports.executeQueryWithConfig = executeQueryWithConfig;
 exports.exportUserCollection = exportUserCollection;
@@ -1030,14 +1106,18 @@ exports.listAgents = listAgents;
 exports.listDataSources = listDataSources;
 exports.listDatasets = listDatasets;
 exports.listGitHubRepos = listGitHubRepos;
+exports.listMessages = listMessages;
 exports.listModels = listModels;
 exports.listReports = listReports;
 exports.listScripts = listScripts;
 exports.listSites = listSites;
+exports.listThreads = listThreads;
 exports.listUsers = listUsers;
 exports.listVisualizations = listVisualizations;
 exports.listWorkspaces = listWorkspaces;
 exports.login = login;
+exports.markMessageRead = markMessageRead;
+exports.openThread = openThread;
 exports.previewPiiMasking = previewPiiMasking;
 exports.promoteSiteVersion = promoteSiteVersion;
 exports.publishStagedSite = publishStagedSite;
@@ -1047,6 +1127,7 @@ exports.reactivateUser = reactivateUser;
 exports.register = register;
 exports.removePiiAllowlistTerm = removePiiAllowlistTerm;
 exports.removeSiteAlias = removeSiteAlias;
+exports.sendMessage = sendMessage;
 exports.setCached = setCached;
 exports.setCachedDatasets = setCachedDatasets;
 exports.setCachedReports = setCachedReports;