@palettelab/sdk 0.1.24 → 0.1.26

package/README.md

@@ -136,6 +136,7 @@ import {
   servicesProxy,
   BrokerCallError,
   events,
+  notifications,
   usePluginTranslations,
   translate,
   normalizePaletteLanguage,
@@ -182,6 +183,7 @@ Public frontend helpers exported by `@palettelab/sdk`:
 - Install config: `getInstallConfig(pluginId)`, `updateInstallConfig(pluginId, values)`.
 - Connections: `getConnections(pluginId)`, `startConnection(pluginId, connectionId)`, `disconnectConnection(pluginId, connectionId)`, and `requireConnection(pluginId, connectionId)`.
 - App-to-app broker: `broker.call(target, payload?)`, `broker.emit(target, payload?)`, `servicesProxy(namespaceVersion)`, `events.on(target, handler)`, `events.emit(target, payload?)`, and `BrokerCallError`.
+- OS notifications: `notifications.push(input)` (also `palette.notifications.push(input)`) — push a persistent notification into the OS notification center.
 - Organization/user: `UserClient`, `OrganizationClient`, including `current`, `updateProfile`, `listMine`, `listMembers`, `getMember`, `getMemberByEmail`, `inviteMember`, and `updateMemberRole`.
 - Permissions: `hasPermission(ctx, permission)`, `hasAnyPermission(ctx, permissions)`, `hasAllPermissions(ctx, permissions)`.
 - Translations: `normalizePaletteLanguage`, `translate`, `usePluginTranslations`.
@@ -503,6 +505,36 @@ const file = folder
   : null
 ```
 
+## OS Notifications
+
+Push a persistent notification into the OS notification center (the bell).
+Unlike a toast, it survives past the moment, shows your app's icon and name,
+and opens/focuses your app window when clicked:
+
+```ts
+import { notifications } from "@palettelab/sdk"
+// or: palette.notifications.push(...)
+
+await notifications.push({
+  title: "Export complete",
+  body: "Your report is ready to download.",
+  severity: "success",          // "info" | "success" | "warning" | "error"
+  route: "/exports/123",        // opened inside your app on click
+  data: { exportId: 123 },      // arbitrary payload stored with the notification
+})
+```
+
+`route` resolves relative to your app (`/apps/{your-app-id}/exports/123`); pass
+an absolute `/apps/...` route to target another app's window. The source app id
+is inferred from the URL — pass `appId` to override.
+
+The stable contract is `POST /api/v1/notifications/` on the platform API; the
+helper is sugar over it. Notifications target the calling user and their active
+organisation, are delivered live over `GET /api/v1/notifications/stream` (SSE),
+and show as a toast plus a notification-center entry. The helper runs in the
+user's session, so sandboxed iframe apps are not supported yet (no session
+cookie inside the iframe).
+
 ## Permissions
 
 Use permission helpers to keep UI actions aligned with backend permission gates.

package/dist/index.d.mts

@@ -189,6 +189,56 @@ declare const broker: {
 /** Typed proxy: `palette.services("org/v1").members.list({ ... })`. */
 declare function servicesProxy(namespaceVersion: string): any;
 
+/**
+ * OS notifications — push a notification into the OS-level notification pool.
+ *
+ *   import { notifications } from "@palettelab/sdk"
+ *
+ *   await notifications.push({
+ *     title: "Export complete",
+ *     body: "Your report is ready to download.",
+ *     severity: "success",
+ *     route: "/exports/123",          // opened inside this app when clicked
+ *   })
+ *
+ * The notification appears in the OS notification center (and as a transient
+ * toast); clicking it opens/focuses the app window at `action_route`.
+ *
+ * The stable contract is `POST /api/v1/notifications/` on the platform API —
+ * this helper is sugar over it. Runs in the user's session (cookies included);
+ * sandboxed iframe apps are not supported yet (no session in the iframe).
+ */
+type OsNotificationSeverity = "info" | "success" | "warning" | "error";
+type OsNotificationInput = {
+    title: string;
+    body?: string;
+    /**
+     * Route to open when the notification is clicked. Relative routes
+     * ("/exports/123") resolve inside the calling app; absolute routes
+     * ("/apps/other-app") are used as-is.
+     */
+    route?: string;
+    severity?: OsNotificationSeverity;
+    /** Arbitrary structured payload, stored alongside the notification. */
+    data?: Record<string, unknown>;
+    /** Override the source app id. Inferred from the URL when omitted. */
+    appId?: string;
+};
+type OsNotification = {
+    id: number;
+    type: string;
+    title: string;
+    body: string | null;
+    source_app_id: string | null;
+    action_route: string | null;
+    severity: OsNotificationSeverity | null;
+    is_read: boolean;
+    created_at: string;
+};
+declare const notifications: {
+    push(input: OsNotificationInput): Promise<OsNotification>;
+};
+
 interface DataRoomContents {
     room?: DataRoom;
     folders: DataRoomFolder[];
@@ -350,6 +400,13 @@ declare function createPaletteClient(ctx?: PlatformContext): {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+        push: (input: OsNotificationInput) => Promise<OsNotification>;
+    };
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -397,6 +454,13 @@ declare const palette: {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+        push: (input: OsNotificationInput) => Promise<OsNotification>;
+    };
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -423,4 +487,4 @@ declare function hasPermission(ctx: PlatformContext, permission: string): boolea
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };
+export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, type OsNotification, type OsNotificationInput, type OsNotificationSeverity, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, notifications, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };

package/dist/index.d.ts

@@ -189,6 +189,56 @@ declare const broker: {
 /** Typed proxy: `palette.services("org/v1").members.list({ ... })`. */
 declare function servicesProxy(namespaceVersion: string): any;
 
+/**
+ * OS notifications — push a notification into the OS-level notification pool.
+ *
+ *   import { notifications } from "@palettelab/sdk"
+ *
+ *   await notifications.push({
+ *     title: "Export complete",
+ *     body: "Your report is ready to download.",
+ *     severity: "success",
+ *     route: "/exports/123",          // opened inside this app when clicked
+ *   })
+ *
+ * The notification appears in the OS notification center (and as a transient
+ * toast); clicking it opens/focuses the app window at `action_route`.
+ *
+ * The stable contract is `POST /api/v1/notifications/` on the platform API —
+ * this helper is sugar over it. Runs in the user's session (cookies included);
+ * sandboxed iframe apps are not supported yet (no session in the iframe).
+ */
+type OsNotificationSeverity = "info" | "success" | "warning" | "error";
+type OsNotificationInput = {
+    title: string;
+    body?: string;
+    /**
+     * Route to open when the notification is clicked. Relative routes
+     * ("/exports/123") resolve inside the calling app; absolute routes
+     * ("/apps/other-app") are used as-is.
+     */
+    route?: string;
+    severity?: OsNotificationSeverity;
+    /** Arbitrary structured payload, stored alongside the notification. */
+    data?: Record<string, unknown>;
+    /** Override the source app id. Inferred from the URL when omitted. */
+    appId?: string;
+};
+type OsNotification = {
+    id: number;
+    type: string;
+    title: string;
+    body: string | null;
+    source_app_id: string | null;
+    action_route: string | null;
+    severity: OsNotificationSeverity | null;
+    is_read: boolean;
+    created_at: string;
+};
+declare const notifications: {
+    push(input: OsNotificationInput): Promise<OsNotification>;
+};
+
 interface DataRoomContents {
     room?: DataRoom;
     folders: DataRoomFolder[];
@@ -350,6 +400,13 @@ declare function createPaletteClient(ctx?: PlatformContext): {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+        push: (input: OsNotificationInput) => Promise<OsNotification>;
+    };
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -397,6 +454,13 @@ declare const palette: {
         error: (message: string) => void | undefined;
         info: (message: string) => void | undefined;
     };
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+        push: (input: OsNotificationInput) => Promise<OsNotification>;
+    };
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -423,4 +487,4 @@ declare function hasPermission(ctx: PlatformContext, permission: string): boolea
 declare function hasAnyPermission(ctx: PlatformContext, permissions: string[]): boolean;
 declare function hasAllPermissions(ctx: PlatformContext, permissions: string[]): boolean;
 
-export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };
+export { BrokerCallError, type BrokerCallOptions, type ConnectionAuthStart, type ConnectionStatus, type ConnectionStatusValue, CrossAppGrantError, DataRoom, DataRoomClient, type DataRoomContents, DataRoomFile, DataRoomFolder, type DataRoomUploadOptions, type EventMeta, type InstallConfig, MissingDependencyError, type OrgInviteMemberInput, type OrgInviteMemberResponse, type OrgMember, type OrgMemberRole, OrgSummary, OrganizationClient, type OsNotification, type OsNotificationInput, type OsNotificationSeverity, PaletteApiError, type PaletteClient, PlatformContext, type SandboxBridge, type SandboxBrokerMessage, StorageClient, type StorageUploadOptions, type StorageUploadProgress, type StorageUploadResult, type StorageUploadState, User, UserClient, apiFetch, apiUpload, broker, createMockPlatformContext, createPaletteClient, createSandboxBridge, dataRooms, disconnectConnection, errorFromResponse, events, getBaseUrl, getConnections, getInstallConfig, hasAllPermissions, hasAnyPermission, hasPermission, isPaletteApiError, isSandboxRuntime, notifications, palette, requireConnection, servicesProxy, setBaseUrl, startConnection, updateInstallConfig, uploadToSignedUrl, withPluginProvider };

package/dist/index.js

@@ -52,6 +52,7 @@ __export(src_exports, {
   isSandboxRuntime: () => isSandboxRuntime,
   normalizePaletteLanguage: () => normalizePaletteLanguage,
   notFound: () => notFound,
+  notifications: () => notifications,
   palette: () => palette,
   requireConnection: () => requireConnection,
   servicesProxy: () => servicesProxy,
@@ -400,6 +401,13 @@ var DataRoomClient = class {
 };
 var dataRooms = new DataRoomClient();
 
+// src/plugin-id.ts
+function currentPluginId() {
+  if (typeof window === "undefined") return void 0;
+  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
+  return match ? decodeURIComponent(match[1]) : void 0;
+}
+
 // src/services.ts
 var BrokerCallError = class extends Error {
   constructor(message, target, status) {
@@ -432,11 +440,6 @@ function brokerError(message, target, status) {
   return new BrokerCallError(message, target, status);
 }
 var CALLER_HEADER = "X-Palette-Caller-App";
-function currentPluginId() {
-  if (typeof window === "undefined") return void 0;
-  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
-  return match ? decodeURIComponent(match[1]) : void 0;
-}
 async function brokerCallDirect(target, payload, options = {}) {
   const callerAppId = options.callerAppId ?? currentPluginId();
   const headers = {};
@@ -561,16 +564,11 @@ var SUBSCRIBERS = /* @__PURE__ */ new Map();
 var activeStream = null;
 var activeStreamUrl = null;
 var sandboxBound = false;
-function currentPluginId2() {
-  if (typeof window === "undefined") return void 0;
-  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
-  return match ? decodeURIComponent(match[1]) : void 0;
-}
 function streamUrl() {
   const params = new URLSearchParams();
   const targets = Array.from(SUBSCRIBERS.keys());
   if (targets.length) params.set("targets", targets.join(","));
-  const callerAppId = currentPluginId2();
+  const callerAppId = currentPluginId();
   if (callerAppId) params.set("caller_app_id", callerAppId);
   const query = params.toString();
   return `${getBaseUrl()}/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
@@ -666,6 +664,32 @@ var events = {
   }
 };
 
+// src/notifications.ts
+function resolveActionRoute(route, appId) {
+  if (!route) return appId ? `/apps/${appId}` : void 0;
+  if (route.startsWith("/apps/")) return route;
+  if (!appId) return route;
+  return `/apps/${appId}${route.startsWith("/") ? route : `/${route}`}`;
+}
+var notifications = {
+  async push(input) {
+    const appId = input.appId ?? currentPluginId();
+    const res = await apiFetch("/api/v1/notifications/", {
+      method: "POST",
+      body: JSON.stringify({
+        title: input.title,
+        body: input.body,
+        type: "app",
+        source_app_id: appId,
+        action_route: resolveActionRoute(input.route, appId),
+        severity: input.severity,
+        data: input.data
+      })
+    });
+    return await res.json();
+  }
+};
+
 // src/permissions.ts
 function hasPermission(ctx, permission) {
   return ctx.permissions?.includes(permission) ?? false;
@@ -996,6 +1020,13 @@ function createPaletteClient(ctx) {
       error: (message) => ctx?.showToast(message, "error"),
       info: (message) => ctx?.showToast(message, "info")
     },
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+      push: (input) => notifications.push({ appId: ctx?.pluginId || void 0, ...input })
+    },
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -1504,6 +1535,7 @@ function usePluginChat(agentId) {
   isSandboxRuntime,
   normalizePaletteLanguage,
   notFound,
+  notifications,
   palette,
   requireConnection,
   servicesProxy,

package/dist/index.mjs

@@ -325,6 +325,13 @@ var DataRoomClient = class {
 };
 var dataRooms = new DataRoomClient();
 
+// src/plugin-id.ts
+function currentPluginId() {
+  if (typeof window === "undefined") return void 0;
+  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
+  return match ? decodeURIComponent(match[1]) : void 0;
+}
+
 // src/services.ts
 var BrokerCallError = class extends Error {
   constructor(message, target, status) {
@@ -357,11 +364,6 @@ function brokerError(message, target, status) {
   return new BrokerCallError(message, target, status);
 }
 var CALLER_HEADER = "X-Palette-Caller-App";
-function currentPluginId() {
-  if (typeof window === "undefined") return void 0;
-  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
-  return match ? decodeURIComponent(match[1]) : void 0;
-}
 async function brokerCallDirect(target, payload, options = {}) {
   const callerAppId = options.callerAppId ?? currentPluginId();
   const headers = {};
@@ -486,16 +488,11 @@ var SUBSCRIBERS = /* @__PURE__ */ new Map();
 var activeStream = null;
 var activeStreamUrl = null;
 var sandboxBound = false;
-function currentPluginId2() {
-  if (typeof window === "undefined") return void 0;
-  const match = window.location.pathname.match(/\/apps\/([^/?#]+)/);
-  return match ? decodeURIComponent(match[1]) : void 0;
-}
 function streamUrl() {
   const params = new URLSearchParams();
   const targets = Array.from(SUBSCRIBERS.keys());
   if (targets.length) params.set("targets", targets.join(","));
-  const callerAppId = currentPluginId2();
+  const callerAppId = currentPluginId();
   if (callerAppId) params.set("caller_app_id", callerAppId);
   const query = params.toString();
   return `${getBaseUrl()}/api/v1/os-broker/events/stream${query ? `?${query}` : ""}`;
@@ -591,6 +588,32 @@ var events = {
   }
 };
 
+// src/notifications.ts
+function resolveActionRoute(route, appId) {
+  if (!route) return appId ? `/apps/${appId}` : void 0;
+  if (route.startsWith("/apps/")) return route;
+  if (!appId) return route;
+  return `/apps/${appId}${route.startsWith("/") ? route : `/${route}`}`;
+}
+var notifications = {
+  async push(input) {
+    const appId = input.appId ?? currentPluginId();
+    const res = await apiFetch("/api/v1/notifications/", {
+      method: "POST",
+      body: JSON.stringify({
+        title: input.title,
+        body: input.body,
+        type: "app",
+        source_app_id: appId,
+        action_route: resolveActionRoute(input.route, appId),
+        severity: input.severity,
+        data: input.data
+      })
+    });
+    return await res.json();
+  }
+};
+
 // src/permissions.ts
 function hasPermission(ctx, permission) {
   return ctx.permissions?.includes(permission) ?? false;
@@ -921,6 +944,13 @@ function createPaletteClient(ctx) {
       error: (message) => ctx?.showToast(message, "error"),
       info: (message) => ctx?.showToast(message, "info")
     },
+    /**
+     * OS notification pool. Unlike `toast`, these persist in the OS
+     * notification center and can open the app when clicked.
+     */
+    notifications: {
+      push: (input) => notifications.push({ appId: ctx?.pluginId || void 0, ...input })
+    },
     /**
      * OS-broker RPC. Typed entry point: `palette.services("org/v1").members.list({...})`.
      * The proxy resolves a dotted method chain into a qualified target string
@@ -1437,6 +1467,7 @@ export {
   isSandboxRuntime,
   normalizePaletteLanguage,
   notFound,
+  notifications,
   palette,
   requireConnection,
   servicesProxy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/sdk",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Palette Platform SDK for building plugins and apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",