@palettelab/sdk 0.1.9 → 0.1.11

package/README.md

@@ -122,6 +122,7 @@ import {
   PluginProvider,
   usePlatform,
   createPaletteClient,
+  usePluginTranslations,
   usePluginTasks,
   usePluginDataRooms,
   usePluginChat,
@@ -169,6 +170,37 @@ export default function PluginRoot(props: PluginComponentProps) {
 }
 ```
 
+## App Translations And OS Language
+
+Palette OS passes the current global language into every plugin through
+`usePlatform()`. Keep translations in your app repo, then let the SDK choose the
+right language.
+
+```tsx
+import { usePluginTranslations, type TranslationResources } from "@palettelab/sdk"
+
+const resources = {
+  en: { title: "Invoices", greeting: "Hello, {{name}}" },
+  ko: { title: "청구서", greeting: "안녕하세요, {{name}}님" },
+} satisfies TranslationResources
+
+function App() {
+  const { t, language, setLanguage } = usePluginTranslations(resources)
+
+  return (
+    <main>
+      <h1>{t("title")}</h1>
+      <button onClick={() => setLanguage(language === "ko" ? "en" : "ko")}>
+        {language === "ko" ? "EN" : "KO"}
+      </button>
+    </main>
+  )
+}
+```
+
+The same context is available in `pltt dev`, so local development and OS runtime
+use the same translation path.
+
 ## Palette Client
 
 Use `createPaletteClient()` when an app needs common Palette OS services without
@@ -195,7 +227,7 @@ Included clients:
 
 - `palette.user.current()` and `palette.user.updateProfile()`
 - `palette.organization.currentId()`, `currentRole()`, and `listMine()`
-- `palette.dataRooms.list()`, `create()`, `get()`, `folder()`, and `uploadFile()`
+- `palette.dataRooms.list()`, `create()`, `get()`, `folder()`, `createFolder()`, `ensureFolder()`, `findRoomByName()`, `findFolderByName()`, `resolveFolderPath()`, `findFileByName()`, and `uploadFile()`
 - `palette.config.get()` and `palette.config.update(values)`, with optional plugin ID override
 - `palette.permissions.has()`, `hasAny()`, and `hasAll()`
 - `palette.storage.uploadToSignedUrl()`
@@ -204,6 +236,41 @@ Included clients:
 These helpers are intentionally thin wrappers over platform APIs. Apps can still
 use `apiFetch()` directly for custom backend routes.
 
+### Data Room Folders By Name
+
+Apps can create or reuse custom Data Room folders by name:
+
+```tsx
+const palette = createPaletteClient(usePlatform())
+
+const room = await palette.dataRooms.ensureRoom("Finance")
+const invoices = await palette.dataRooms.ensureFolder(room.id, "Invoices")
+
+await palette.dataRooms.uploadFile(room.id, file, {
+  folderId: invoices.id,
+})
+```
+
+Apps can also resolve nested folders:
+
+```tsx
+const folder = await palette.dataRooms.resolveFolderPath(
+  room.id,
+  "Clients/Acme/Invoices",
+  { create: true },
+)
+```
+
+To read existing files by name:
+
+```tsx
+const room = await palette.dataRooms.requireRoomByName("Finance")
+const folder = await palette.dataRooms.resolveFolderPath(room.id, "Clients/Acme/Invoices")
+const file = folder
+  ? await palette.dataRooms.findFileByName(room.id, "jan.pdf", { folderId: folder.id })
+  : null
+```
+
 ## Permissions
 
 Use permission helpers to keep UI actions aligned with backend permission gates.
@@ -297,7 +364,7 @@ Use the SDK test utilities to render plugin components with a mock platform cont
 import { createMockPlatformContext, withPluginProvider } from "@palettelab/sdk"
 
 const ctx = createMockPlatformContext({
-  pluginId: "hello-sdk",
+  pluginId: "my-plugin",
   organizationId: 1,
 })
 

package/dist/components/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import react__default from 'react';
-import { P as PlatformContext } from '../plugin-o-qmdCBl.mjs';
+import { P as PlatformContext } from '../plugin-DZRaxKt3.mjs';
 
 /**
  * Provider that wraps plugin components with the platform context.

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import react__default from 'react';
-import { P as PlatformContext } from '../plugin-o-qmdCBl.js';
+import { P as PlatformContext } from '../plugin-DZRaxKt3.js';
 
 /**
  * Provider that wraps plugin components with the platform context.

package/dist/hooks/index.d.mts

@@ -1,71 +1,4 @@
-import * as react from 'react';
-import { P as PlatformContext } from '../plugin-o-qmdCBl.mjs';
-import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from '../data-room-Dtd9LLHf.mjs';
-
-/**
- * React context for platform services.
- * The platform runtime provides this — plugin developers consume it.
- */
-declare const PlatformCtx: react.Context<PlatformContext | null>;
-/**
- * Access the platform context from within a plugin component.
- *
- * Provides: user, organizationId, agents, apiFetch, navigate, showToast
- *
- * @example
- * ```tsx
- * import { usePlatform } from "@palettelab/sdk/hooks"
- *
- * function MyPlugin() {
- *   const { user, apiFetch, showToast } = usePlatform()
- *   // ...
- * }
- * ```
- */
-declare function usePlatform(): PlatformContext;
-
-/**
- * Hook for managing tasks from within a plugin.
- *
- * @param agentId - Optional agent ID to filter tasks
- */
-declare function usePluginTasks(agentId?: number): {
-    tasks: Task[];
-    stats: TaskStats | null;
-    loading: boolean;
-    createTask: (payload: TaskCreatePayload) => Promise<Task>;
-    updateTask: (taskId: number, payload: TaskUpdatePayload) => Promise<Task>;
-    deleteTask: (taskId: number) => Promise<void>;
-    refetch: () => Promise<void>;
-};
-
-/**
- * Hook for accessing data rooms from within a plugin.
- */
-declare function usePluginDataRooms(): {
-    rooms: DataRoom[];
-    loading: boolean;
-    fetchFolder: (roomId: number, folderId?: number) => Promise<{
-        folders: DataRoomFolder[];
-        files: DataRoomFile[];
-    }>;
-    refetch: () => Promise<void>;
-};
-
-/**
- * Hook for chat functionality within a plugin.
- * Supports creating threads, sending messages, and SSE streaming.
- */
-declare function usePluginChat(agentId: number): {
-    threads: ChatThread[];
-    messages: ChatMessage[];
-    streaming: boolean;
-    activeThreadId: string | null;
-    fetchThreads: () => Promise<void>;
-    createThread: () => Promise<ChatThread>;
-    fetchMessages: (threadId: string) => Promise<void>;
-    sendMessage: (threadId: string, content: string) => Promise<void>;
-    stopStreaming: () => void;
-};
-
-export { PlatformCtx, usePlatform, usePluginChat, usePluginDataRooms, usePluginTasks };
+export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-BL37Z-Ns.mjs';
+import 'react';
+import '../plugin-DZRaxKt3.mjs';
+import '../data-room-Dtd9LLHf.mjs';

package/dist/hooks/index.d.ts

@@ -1,71 +1,4 @@
-import * as react from 'react';
-import { P as PlatformContext } from '../plugin-o-qmdCBl.js';
-import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from '../data-room-Dtd9LLHf.js';
-
-/**
- * React context for platform services.
- * The platform runtime provides this — plugin developers consume it.
- */
-declare const PlatformCtx: react.Context<PlatformContext | null>;
-/**
- * Access the platform context from within a plugin component.
- *
- * Provides: user, organizationId, agents, apiFetch, navigate, showToast
- *
- * @example
- * ```tsx
- * import { usePlatform } from "@palettelab/sdk/hooks"
- *
- * function MyPlugin() {
- *   const { user, apiFetch, showToast } = usePlatform()
- *   // ...
- * }
- * ```
- */
-declare function usePlatform(): PlatformContext;
-
-/**
- * Hook for managing tasks from within a plugin.
- *
- * @param agentId - Optional agent ID to filter tasks
- */
-declare function usePluginTasks(agentId?: number): {
-    tasks: Task[];
-    stats: TaskStats | null;
-    loading: boolean;
-    createTask: (payload: TaskCreatePayload) => Promise<Task>;
-    updateTask: (taskId: number, payload: TaskUpdatePayload) => Promise<Task>;
-    deleteTask: (taskId: number) => Promise<void>;
-    refetch: () => Promise<void>;
-};
-
-/**
- * Hook for accessing data rooms from within a plugin.
- */
-declare function usePluginDataRooms(): {
-    rooms: DataRoom[];
-    loading: boolean;
-    fetchFolder: (roomId: number, folderId?: number) => Promise<{
-        folders: DataRoomFolder[];
-        files: DataRoomFile[];
-    }>;
-    refetch: () => Promise<void>;
-};
-
-/**
- * Hook for chat functionality within a plugin.
- * Supports creating threads, sending messages, and SSE streaming.
- */
-declare function usePluginChat(agentId: number): {
-    threads: ChatThread[];
-    messages: ChatMessage[];
-    streaming: boolean;
-    activeThreadId: string | null;
-    fetchThreads: () => Promise<void>;
-    createThread: () => Promise<ChatThread>;
-    fetchMessages: (threadId: string) => Promise<void>;
-    sendMessage: (threadId: string, content: string) => Promise<void>;
-    stopStreaming: () => void;
-};
-
-export { PlatformCtx, usePlatform, usePluginChat, usePluginDataRooms, usePluginTasks };
+export { P as PlatformCtx, u as usePlatform, e as usePluginChat, f as usePluginDataRooms, g as usePluginTasks, h as usePluginTranslations } from '../index-DEvPH60n.js';
+import 'react';
+import '../plugin-DZRaxKt3.js';
+import '../data-room-Dtd9LLHf.js';

package/dist/hooks/index.js

@@ -24,7 +24,8 @@ __export(hooks_exports, {
   usePlatform: () => usePlatform,
   usePluginChat: () => usePluginChat,
   usePluginDataRooms: () => usePluginDataRooms,
-  usePluginTasks: () => usePluginTasks
+  usePluginTasks: () => usePluginTasks,
+  usePluginTranslations: () => usePluginTranslations
 });
 module.exports = __toCommonJS(hooks_exports);
 
@@ -242,11 +243,75 @@ function usePluginChat(agentId) {
     stopStreaming
   };
 }
+
+// src/i18n.ts
+var import_react5 = require("react");
+function normalizePaletteLanguage(language, fallback = "en") {
+  const trimmed = language?.trim().toLowerCase();
+  if (!trimmed) return fallback;
+  return trimmed.split("-")[0] || fallback;
+}
+function languageCandidates(language, fallbackLanguage = "en") {
+  const candidates = [
+    language,
+    normalizePaletteLanguage(language, fallbackLanguage),
+    fallbackLanguage,
+    normalizePaletteLanguage(fallbackLanguage, "en"),
+    "en"
+  ].filter(Boolean);
+  return Array.from(new Set(candidates));
+}
+function getValue(dictionary, key) {
+  if (!dictionary) return void 0;
+  let current = dictionary;
+  for (const part of key.split(".")) {
+    if (current === null || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[part];
+  }
+  if (typeof current === "string" || typeof current === "number" || typeof current === "boolean" || current === null) {
+    return current;
+  }
+  return void 0;
+}
+function interpolate(template, values) {
+  if (!values) return template;
+  return template.replace(/\{\{?\s*([a-zA-Z0-9_.-]+)\s*\}?\}/g, (match, key) => {
+    const value = values[key];
+    return value === void 0 || value === null ? match : String(value);
+  });
+}
+function translate(resources, key, options = {}) {
+  const fallbackLanguage = normalizePaletteLanguage(options.fallbackLanguage, "en");
+  for (const language of languageCandidates(options.language, fallbackLanguage)) {
+    const value = getValue(resources[language], key);
+    if (value !== void 0) {
+      return interpolate(String(value ?? ""), options.values);
+    }
+  }
+  return interpolate(options.defaultValue ?? key, options.values);
+}
+function usePluginTranslations(resources, options = {}) {
+  const platform = usePlatform();
+  const language = normalizePaletteLanguage(platform.language, options.fallbackLanguage ?? platform.fallbackLanguage);
+  const fallbackLanguage = normalizePaletteLanguage(options.fallbackLanguage ?? platform.fallbackLanguage, "en");
+  const t = (0, import_react5.useCallback)(
+    (key, values, defaultValue) => translate(resources, key, { language, fallbackLanguage, values, defaultValue }),
+    [fallbackLanguage, language, resources]
+  );
+  return {
+    language,
+    fallbackLanguage,
+    supportedLanguages: platform.supportedLanguages,
+    setLanguage: platform.setLanguage,
+    t
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PlatformCtx,
   usePlatform,
   usePluginChat,
   usePluginDataRooms,
-  usePluginTasks
+  usePluginTasks,
+  usePluginTranslations
 });

package/dist/hooks/index.mjs

@@ -212,10 +212,74 @@ function usePluginChat(agentId) {
     stopStreaming
   };
 }
+
+// src/i18n.ts
+import { useCallback as useCallback4 } from "react";
+function normalizePaletteLanguage(language, fallback = "en") {
+  const trimmed = language?.trim().toLowerCase();
+  if (!trimmed) return fallback;
+  return trimmed.split("-")[0] || fallback;
+}
+function languageCandidates(language, fallbackLanguage = "en") {
+  const candidates = [
+    language,
+    normalizePaletteLanguage(language, fallbackLanguage),
+    fallbackLanguage,
+    normalizePaletteLanguage(fallbackLanguage, "en"),
+    "en"
+  ].filter(Boolean);
+  return Array.from(new Set(candidates));
+}
+function getValue(dictionary, key) {
+  if (!dictionary) return void 0;
+  let current = dictionary;
+  for (const part of key.split(".")) {
+    if (current === null || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[part];
+  }
+  if (typeof current === "string" || typeof current === "number" || typeof current === "boolean" || current === null) {
+    return current;
+  }
+  return void 0;
+}
+function interpolate(template, values) {
+  if (!values) return template;
+  return template.replace(/\{\{?\s*([a-zA-Z0-9_.-]+)\s*\}?\}/g, (match, key) => {
+    const value = values[key];
+    return value === void 0 || value === null ? match : String(value);
+  });
+}
+function translate(resources, key, options = {}) {
+  const fallbackLanguage = normalizePaletteLanguage(options.fallbackLanguage, "en");
+  for (const language of languageCandidates(options.language, fallbackLanguage)) {
+    const value = getValue(resources[language], key);
+    if (value !== void 0) {
+      return interpolate(String(value ?? ""), options.values);
+    }
+  }
+  return interpolate(options.defaultValue ?? key, options.values);
+}
+function usePluginTranslations(resources, options = {}) {
+  const platform = usePlatform();
+  const language = normalizePaletteLanguage(platform.language, options.fallbackLanguage ?? platform.fallbackLanguage);
+  const fallbackLanguage = normalizePaletteLanguage(options.fallbackLanguage ?? platform.fallbackLanguage, "en");
+  const t = useCallback4(
+    (key, values, defaultValue) => translate(resources, key, { language, fallbackLanguage, values, defaultValue }),
+    [fallbackLanguage, language, resources]
+  );
+  return {
+    language,
+    fallbackLanguage,
+    supportedLanguages: platform.supportedLanguages,
+    setLanguage: platform.setLanguage,
+    t
+  };
+}
 export {
   PlatformCtx,
   usePlatform,
   usePluginChat,
   usePluginDataRooms,
-  usePluginTasks
+  usePluginTasks,
+  usePluginTranslations
 };

package/dist/index-BL37Z-Ns.d.mts

@@ -0,0 +1,96 @@
+import * as react from 'react';
+import { d as PaletteLanguage, P as PlatformContext } from './plugin-DZRaxKt3.mjs';
+import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from './data-room-Dtd9LLHf.mjs';
+
+type TranslationPrimitive = string | number | boolean | null;
+type TranslationDictionary = {
+    [key: string]: TranslationPrimitive | TranslationDictionary;
+};
+type TranslationResources = Record<PaletteLanguage, TranslationDictionary>;
+type TranslationValues = Record<string, string | number | boolean | null | undefined>;
+interface TranslateOptions {
+    language?: PaletteLanguage;
+    fallbackLanguage?: PaletteLanguage;
+    defaultValue?: string;
+    values?: TranslationValues;
+}
+interface UsePluginTranslationsOptions {
+    fallbackLanguage?: PaletteLanguage;
+}
+declare function normalizePaletteLanguage(language?: string | null, fallback?: PaletteLanguage): PaletteLanguage;
+declare function translate(resources: TranslationResources, key: string, options?: TranslateOptions): string;
+declare function usePluginTranslations(resources: TranslationResources, options?: UsePluginTranslationsOptions): {
+    language: string;
+    fallbackLanguage: string;
+    supportedLanguages: string[];
+    setLanguage: (language: PaletteLanguage) => void;
+    t: (key: string, values?: TranslationValues, defaultValue?: string) => string;
+};
+
+/**
+ * React context for platform services.
+ * The platform runtime provides this — plugin developers consume it.
+ */
+declare const PlatformCtx: react.Context<PlatformContext | null>;
+/**
+ * Access the platform context from within a plugin component.
+ *
+ * Provides: user, organizationId, agents, apiFetch, navigate, showToast
+ *
+ * @example
+ * ```tsx
+ * import { usePlatform } from "@palettelab/sdk/hooks"
+ *
+ * function MyPlugin() {
+ *   const { user, apiFetch, showToast } = usePlatform()
+ *   // ...
+ * }
+ * ```
+ */
+declare function usePlatform(): PlatformContext;
+
+/**
+ * Hook for managing tasks from within a plugin.
+ *
+ * @param agentId - Optional agent ID to filter tasks
+ */
+declare function usePluginTasks(agentId?: number): {
+    tasks: Task[];
+    stats: TaskStats | null;
+    loading: boolean;
+    createTask: (payload: TaskCreatePayload) => Promise<Task>;
+    updateTask: (taskId: number, payload: TaskUpdatePayload) => Promise<Task>;
+    deleteTask: (taskId: number) => Promise<void>;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook for accessing data rooms from within a plugin.
+ */
+declare function usePluginDataRooms(): {
+    rooms: DataRoom[];
+    loading: boolean;
+    fetchFolder: (roomId: number, folderId?: number) => Promise<{
+        folders: DataRoomFolder[];
+        files: DataRoomFile[];
+    }>;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook for chat functionality within a plugin.
+ * Supports creating threads, sending messages, and SSE streaming.
+ */
+declare function usePluginChat(agentId: number): {
+    threads: ChatThread[];
+    messages: ChatMessage[];
+    streaming: boolean;
+    activeThreadId: string | null;
+    fetchThreads: () => Promise<void>;
+    createThread: () => Promise<ChatThread>;
+    fetchMessages: (threadId: string) => Promise<void>;
+    sendMessage: (threadId: string, content: string) => Promise<void>;
+    stopStreaming: () => void;
+};
+
+export { PlatformCtx as P, type TranslateOptions as T, type UsePluginTranslationsOptions as U, type TranslationDictionary as a, type TranslationPrimitive as b, type TranslationResources as c, type TranslationValues as d, usePluginChat as e, usePluginDataRooms as f, usePluginTasks as g, usePluginTranslations as h, normalizePaletteLanguage as n, translate as t, usePlatform as u };

package/dist/index-DEvPH60n.d.ts

@@ -0,0 +1,96 @@
+import * as react from 'react';
+import { d as PaletteLanguage, P as PlatformContext } from './plugin-DZRaxKt3.js';
+import { T as Task, i as TaskStats, g as TaskCreatePayload, l as TaskUpdatePayload, D as DataRoom, a as DataRoomFolder, b as DataRoomFile, d as ChatThread, c as ChatMessage } from './data-room-Dtd9LLHf.js';
+
+type TranslationPrimitive = string | number | boolean | null;
+type TranslationDictionary = {
+    [key: string]: TranslationPrimitive | TranslationDictionary;
+};
+type TranslationResources = Record<PaletteLanguage, TranslationDictionary>;
+type TranslationValues = Record<string, string | number | boolean | null | undefined>;
+interface TranslateOptions {
+    language?: PaletteLanguage;
+    fallbackLanguage?: PaletteLanguage;
+    defaultValue?: string;
+    values?: TranslationValues;
+}
+interface UsePluginTranslationsOptions {
+    fallbackLanguage?: PaletteLanguage;
+}
+declare function normalizePaletteLanguage(language?: string | null, fallback?: PaletteLanguage): PaletteLanguage;
+declare function translate(resources: TranslationResources, key: string, options?: TranslateOptions): string;
+declare function usePluginTranslations(resources: TranslationResources, options?: UsePluginTranslationsOptions): {
+    language: string;
+    fallbackLanguage: string;
+    supportedLanguages: string[];
+    setLanguage: (language: PaletteLanguage) => void;
+    t: (key: string, values?: TranslationValues, defaultValue?: string) => string;
+};
+
+/**
+ * React context for platform services.
+ * The platform runtime provides this — plugin developers consume it.
+ */
+declare const PlatformCtx: react.Context<PlatformContext | null>;
+/**
+ * Access the platform context from within a plugin component.
+ *
+ * Provides: user, organizationId, agents, apiFetch, navigate, showToast
+ *
+ * @example
+ * ```tsx
+ * import { usePlatform } from "@palettelab/sdk/hooks"
+ *
+ * function MyPlugin() {
+ *   const { user, apiFetch, showToast } = usePlatform()
+ *   // ...
+ * }
+ * ```
+ */
+declare function usePlatform(): PlatformContext;
+
+/**
+ * Hook for managing tasks from within a plugin.
+ *
+ * @param agentId - Optional agent ID to filter tasks
+ */
+declare function usePluginTasks(agentId?: number): {
+    tasks: Task[];
+    stats: TaskStats | null;
+    loading: boolean;
+    createTask: (payload: TaskCreatePayload) => Promise<Task>;
+    updateTask: (taskId: number, payload: TaskUpdatePayload) => Promise<Task>;
+    deleteTask: (taskId: number) => Promise<void>;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook for accessing data rooms from within a plugin.
+ */
+declare function usePluginDataRooms(): {
+    rooms: DataRoom[];
+    loading: boolean;
+    fetchFolder: (roomId: number, folderId?: number) => Promise<{
+        folders: DataRoomFolder[];
+        files: DataRoomFile[];
+    }>;
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Hook for chat functionality within a plugin.
+ * Supports creating threads, sending messages, and SSE streaming.
+ */
+declare function usePluginChat(agentId: number): {
+    threads: ChatThread[];
+    messages: ChatMessage[];
+    streaming: boolean;
+    activeThreadId: string | null;
+    fetchThreads: () => Promise<void>;
+    createThread: () => Promise<ChatThread>;
+    fetchMessages: (threadId: string) => Promise<void>;
+    sendMessage: (threadId: string, content: string) => Promise<void>;
+    stopStreaming: () => void;
+};
+
+export { PlatformCtx as P, type TranslateOptions as T, type UsePluginTranslationsOptions as U, type TranslationDictionary as a, type TranslationPrimitive as b, type TranslationResources as c, type TranslationValues as d, usePluginChat as e, usePluginDataRooms as f, usePluginTasks as g, usePluginTranslations as h, normalizePaletteLanguage as n, translate as t, usePlatform as u };