@palettelab/sdk 0.1.24 → 0.1.25

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.25",
   "description": "Palette Platform SDK for building plugins and apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",