@zaflun/lumio-sdk 0.6.3 → 0.10.0

package/dist/server.d.ts

@@ -26,11 +26,56 @@ interface SchemaDefinition {
 declare function defineTable(columns: Record<string, Validator>): TableDefinition;
 declare function defineSchema(tables: Record<string, TableDefinition>): SchemaDefinition;
 
+/** A value supplied by the caller at call time: `getRules({ category: "x" })`. */
+interface ArgExpression {
+    __expr: "arg";
+    name: string;
+}
+/** The caller's identity, resolved server-side (never sent by the caller). */
+interface IdentityExpression {
+    __expr: "identity";
+}
+/** A secret stored with `lumio env set` (handler-based functions only). */
+interface SecretExpression {
+    __expr: "secret";
+    name: string;
+}
+/** Comparison operators accepted by `filter()`. */
+type FilterOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "like" | "in";
+/** A `field op value` condition for `queryRows({ filter })`. */
+interface FilterExpression {
+    __expr: "filter";
+    field: string;
+    op: FilterOperator;
+    value: unknown;
+}
+declare function arg(name: string): ArgExpression;
+declare function identity(): IdentityExpression;
+declare function secret(name: string): SecretExpression;
+declare function filter(field: string, op: FilterOperator, value: unknown): FilterExpression;
+
+interface QueryRowsOptions {
+    /** One condition, or several that must all match. */
+    filter?: FilterExpression | FilterExpression[];
+    /** Column to sort by (default: `created_at`). */
+    orderBy?: string;
+    /** Sort direction (default: `asc`). */
+    orderDir?: "asc" | "desc";
+    /** Maximum rows to return. */
+    limit?: number | ArgExpression;
+    /** Rows to skip (pagination). */
+    offset?: number | ArgExpression;
+}
 interface QueryRowsDefinition {
     __type: "queryRows";
     table: string;
+    filter?: FilterExpression | FilterExpression[];
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    limit?: number | ArgExpression;
+    offset?: number | ArgExpression;
 }
-declare function queryRows(table: string): QueryRowsDefinition;
+declare function queryRows(table: string, opts?: QueryRowsOptions): QueryRowsDefinition;
 
 interface InsertRowDefinition {
     __type: "insertRow";
@@ -46,97 +91,45 @@ declare function insertRow(table: string, values: Record<string, unknown>, opts?
 interface PatchRowDefinition {
     __type: "patchRow";
     table: string;
-    rowId: string;
+    rowId: string | ArgExpression;
     values: Record<string, unknown>;
     editorOnly: boolean;
 }
 interface PatchRowOptions {
     editorOnly?: boolean;
 }
-declare function patchRow(table: string, rowId: string, values: Record<string, unknown>, opts?: PatchRowOptions): PatchRowDefinition;
+declare function patchRow(table: string, rowId: string | ArgExpression, values: Record<string, unknown>, opts?: PatchRowOptions): PatchRowDefinition;
 
 interface DeleteRowDefinition {
     __type: "deleteRow";
     table: string;
-    rowId: string;
+    rowId: string | ArgExpression;
     editorOnly: boolean;
 }
 interface DeleteRowOptions {
     editorOnly?: boolean;
 }
-declare function deleteRow(table: string, rowId: string, opts?: DeleteRowOptions): DeleteRowDefinition;
+declare function deleteRow(table: string, rowId: string | ArgExpression, opts?: DeleteRowOptions): DeleteRowDefinition;
 
-interface HandlerContext {
-    db: {
-        get: (table: string, id: string) => Promise<Record<string, unknown> | null>;
-        insert: (table: string, values: Record<string, unknown>) => Promise<string>;
-        patch: (table: string, id: string, values: Record<string, unknown>) => Promise<void>;
-        delete: (table: string, id: string) => Promise<void>;
-    };
-    fetch: (url: string, opts?: RequestInit) => Promise<Response>;
-    auth: {
-        userId: string | null;
-        accountId: string | null;
-    };
-    secrets: {
-        get: (name: string) => Promise<string | null>;
-    };
-}
-interface HandlerConfig {
-    args: Record<string, Validator>;
-    handler: (ctx: HandlerContext, args: Record<string, unknown>) => Promise<unknown>;
-}
-interface QueryDefinition {
-    __type: "query";
-    args: Record<string, Validator>;
-    handler: HandlerConfig["handler"];
-}
-interface MutationDefinition {
-    __type: "mutation";
-    args: Record<string, Validator>;
-    handler: HandlerConfig["handler"];
-}
-interface ActionDefinition {
-    __type: "action";
-    args: Record<string, Validator>;
-    handler: HandlerConfig["handler"];
-}
-declare function query(config: HandlerConfig): QueryDefinition;
-declare function mutation(config: HandlerConfig): MutationDefinition;
-declare function action(config: HandlerConfig): ActionDefinition;
-
-interface FetchActionDefinition {
-    __type: "fetchAction";
-    url: string;
-    method: string;
-    headers?: Record<string, string>;
-    body?: unknown;
-}
-interface FetchActionOptions {
-    method?: string;
-    headers?: Record<string, string>;
-    body?: unknown;
+/**
+ * `ctx.realtime` — push a message to every rendered surface of this install
+ * (editor and layer), where `useRealtime(topic, cb)` receives it.
+ *
+ * `topic`: 1–64 characters of `A-Z a-z 0-9 _ . : -`, starting with a letter
+ * or digit. `payload`: any JSON value up to 16 KiB serialized (omitted =
+ * `null`). At most 32 pushes per handler run; a push that breaks a rule
+ * throws. Pushes are sent after the handler returns, and only if it does not
+ * throw. Over 300 pushes per install and minute, further pushes are dropped.
+ */
+interface RealtimeApi {
+    push: (topic: string, payload?: unknown) => void;
 }
-declare function fetchAction(url: string, opts?: FetchActionOptions): FetchActionDefinition;
-
-declare function arg(name: string): {
-    __expr: "arg";
-    name: string;
-};
-declare function identity(): {
-    __expr: "identity";
-};
-declare function secret(name: string): {
-    __expr: "secret";
-    name: string;
-};
-declare function filter(field: string, op: string, value: unknown): {
-    __expr: "filter";
+/** One `ctx.db.list` predicate. Every filter must match. */
+interface DbFilter {
     field: string;
-    op: string;
+    op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte";
     value: unknown;
-};
-
+}
 interface BotModuleContext {
     auth: {
         userId: string | null;
@@ -154,12 +147,21 @@ interface BotModuleContext {
         isSub: boolean;
     } | null;
     config: Record<string, unknown>;
+    /**
+     * The extension's tables (declared in `server/schema.ts`), scoped to this
+     * install. Throws `this extension has no data schema` without one.
+     */
     db: {
+        /** The row with `_id === id`, or `null`. */
         get: (table: string, id: string) => Promise<Record<string, unknown> | null>;
-        list: (table: string) => Promise<Record<string, unknown>[]>;
+        /** Rows matching every filter (all rows without filters). */
+        list: (table: string, filters?: DbFilter[]) => Promise<Record<string, unknown>[]>;
+        /** Inserts a row and resolves to its new `_id`. */
         insert: (table: string, row: Record<string, unknown>) => Promise<string>;
-        patch: (table: string, id: string, row: Record<string, unknown>) => Promise<void>;
-        delete: (table: string, id: string) => Promise<void>;
+        /** Updates the given columns; resolves to the updated row, or `null` when no row has `id`. */
+        patch: (table: string, id: string, row: Record<string, unknown>) => Promise<Record<string, unknown> | null>;
+        /** Deletes a row; resolves to whether a row was deleted. */
+        delete: (table: string, id: string) => Promise<boolean>;
     };
     cache: {
         get: (key: string) => Promise<unknown | null>;
@@ -172,6 +174,8 @@ interface BotModuleContext {
     };
     fetch: (url: string, options?: RequestInit) => Promise<Response>;
     defer: (fn: () => Promise<void>) => void;
+    /** Push to every rendered surface of this install (see `RealtimeApi`). */
+    realtime: RealtimeApi;
 }
 interface HandlerResponse {
     reply?: string;
@@ -272,6 +276,72 @@ interface TimerDefinition {
  */
 declare function defineTimer(handler: (ctx: TimerContext) => Promise<HandlerResponse | null>): TimerDefinition;
 
+interface HandlerContext {
+    db: {
+        get: (table: string, id: string) => Promise<Record<string, unknown> | null>;
+        insert: (table: string, values: Record<string, unknown>) => Promise<string>;
+        patch: (table: string, id: string, values: Record<string, unknown>) => Promise<void>;
+        delete: (table: string, id: string) => Promise<void>;
+    };
+    fetch: (url: string, opts?: RequestInit) => Promise<Response>;
+    auth: {
+        userId: string | null;
+        accountId: string | null;
+    };
+    secrets: {
+        get: (name: string) => Promise<string | null>;
+    };
+    /** Push to every rendered surface of this install; see `RealtimeApi`. */
+    realtime: RealtimeApi;
+}
+interface HandlerConfig {
+    args: Record<string, Validator>;
+    /** Only the editor surface (dashboard session, API key) may call it. */
+    editorOnly?: boolean;
+    handler: (ctx: HandlerContext, args: Record<string, unknown>) => Promise<unknown>;
+}
+interface QueryDefinition {
+    __type: "query";
+    args: Record<string, Validator>;
+    editorOnly?: boolean;
+    handler: HandlerConfig["handler"];
+}
+interface MutationDefinition {
+    __type: "mutation";
+    args: Record<string, Validator>;
+    editorOnly?: boolean;
+    handler: HandlerConfig["handler"];
+}
+interface ActionDefinition {
+    __type: "action";
+    args: Record<string, Validator>;
+    editorOnly?: boolean;
+    handler: HandlerConfig["handler"];
+}
+declare function query(config: HandlerConfig): QueryDefinition;
+declare function mutation(config: HandlerConfig): MutationDefinition;
+declare function action(config: HandlerConfig): ActionDefinition;
+
+interface FetchActionDefinition {
+    __type: "fetchAction";
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+interface FetchActionOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+declare function fetchAction(url: string, opts?: FetchActionOptions): FetchActionDefinition;
+
+/**
+ * Every value `server/functions.ts` may export. `lumio build` writes each one
+ * to `dist/functions.json` under its export name.
+ */
+type ServerFunctionDefinition = QueryRowsDefinition | InsertRowDefinition | PatchRowDefinition | DeleteRowDefinition | QueryDefinition | MutationDefinition | ActionDefinition;
+
 interface AutomationNodeContext {
     /** HTTP fetch with egress allowlist enforcement. */
     fetch: (url: string, options?: RequestInit) => Promise<Response>;
@@ -384,4 +454,4 @@ declare function defineAutomationTrigger(handlers: TriggerHandlers): AutomationT
  */
 declare function defineAutomationLogic(handler: LogicHandler): AutomationLogicDefinition;
 
-export { type ActionDefinition, type ActionResult, type AutomationActionDefinition, type AutomationLogicDefinition, type AutomationNodeContext, type AutomationTriggerDefinition, type BotModuleContext, type ChatMessage, type DeleteRowDefinition, type DeleteRowOptions, type FetchActionDefinition, type FetchActionOptions, type HandlerConfig, type HandlerContext, type HandlerResponse, type InsertRowDefinition, type InsertRowOptions, type ModerateContext, type ModerateDefinition, type ModerateResult, type ModerationResponse, type MutationDefinition, type PatchRowDefinition, type PatchRowOptions, type QueryDefinition, type QueryRowsDefinition, type SchemaDefinition, type TableDefinition, type TimerContext, type TimerDefinition, type TriggerNodeContext, type TriggerResult, type Validator, action, arg, command, defineAutomationAction, defineAutomationLogic, defineAutomationTrigger, defineModerate, defineSchema, defineTable, defineTimer, deleteRow, event, fetchAction, filter, identity, insertRow, keyword, moderate, mutation, patchRow, pattern, query, queryRows, secret, timer, v };
+export { type ActionDefinition, type ActionResult, type ArgExpression, type AutomationActionDefinition, type AutomationLogicDefinition, type AutomationNodeContext, type AutomationTriggerDefinition, type BotModuleContext, type ChatMessage, type DbFilter, type DeleteRowDefinition, type DeleteRowOptions, type FetchActionDefinition, type FetchActionOptions, type FilterExpression, type FilterOperator, type HandlerConfig, type HandlerContext, type HandlerResponse, type IdentityExpression, type InsertRowDefinition, type InsertRowOptions, type ModerateContext, type ModerateDefinition, type ModerateResult, type ModerationResponse, type MutationDefinition, type PatchRowDefinition, type PatchRowOptions, type QueryDefinition, type QueryRowsDefinition, type QueryRowsOptions, type RealtimeApi, type SchemaDefinition, type SecretExpression, type ServerFunctionDefinition, type TableDefinition, type TimerContext, type TimerDefinition, type TriggerNodeContext, type TriggerResult, type Validator, action, arg, command, defineAutomationAction, defineAutomationLogic, defineAutomationTrigger, defineModerate, defineSchema, defineTable, defineTimer, deleteRow, event, fetchAction, filter, identity, insertRow, keyword, moderate, mutation, patchRow, pattern, query, queryRows, secret, timer, v };

package/dist/server.js

@@ -42,8 +42,14 @@ var v = {
 };
 
 // src/server/queryRows.ts
-function queryRows(table) {
-  return { __type: "queryRows", table };
+function queryRows(table, opts) {
+  const def = { __type: "queryRows", table };
+  if (opts?.filter !== void 0) def.filter = opts.filter;
+  if (opts?.orderBy !== void 0) def.orderBy = opts.orderBy;
+  if (opts?.orderDir !== void 0) def.orderDir = opts.orderDir;
+  if (opts?.limit !== void 0) def.limit = opts.limit;
+  if (opts?.offset !== void 0) def.offset = opts.offset;
+  return def;
 }
 
 // src/server/insertRow.ts
@@ -79,13 +85,13 @@ function deleteRow(table, rowId, opts) {
 
 // src/server/handlers.ts
 function query(config) {
-  return { __type: "query", args: config.args, handler: config.handler };
+  return { __type: "query", args: config.args, editorOnly: config.editorOnly, handler: config.handler };
 }
 function mutation(config) {
-  return { __type: "mutation", args: config.args, handler: config.handler };
+  return { __type: "mutation", args: config.args, editorOnly: config.editorOnly, handler: config.handler };
 }
 function action(config) {
-  return { __type: "action", args: config.args, handler: config.handler };
+  return { __type: "action", args: config.args, editorOnly: config.editorOnly, handler: config.handler };
 }
 
 // src/server/fetchAction.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zaflun/lumio-sdk",
-  "version": "0.6.3",
-  "description": "Lumio Extension SDK — React components, hooks, and server utilities for building Lumio extensions",
+  "version": "0.10.0",
+  "description": "Lumio Extension SDK - React components, hooks, and server utilities for building Lumio extensions",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,10 @@
       "import": "./dist/server.js",
       "types": "./dist/server.d.ts"
     },
+    "./host": {
+      "import": "./dist/host.js",
+      "types": "./dist/host.d.ts"
+    },
     "./runtime": {
       "import": "./dist/lumio-runtime.global.js"
     }
@@ -23,8 +27,8 @@
   ],
   "dependencies": {
     "react-reconciler": "^0.32.0",
-    "@zaflun/lumio-protocol": "0.2.3",
-    "@zaflun/lumio-extension-types": "0.3.2"
+    "@zaflun/lumio-extension-types": "0.4.0",
+    "@zaflun/lumio-protocol": "0.9.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -32,17 +36,17 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.1.0",
-    "@types/react": "^19.1.0",
-    "@types/react-dom": "^19.1.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
     "@types/react-reconciler": "^0.32.0",
     "jsdom": "^26.1.0",
-    "lucide-static": "^1.16.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "lucide-static": "^1.30.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
+    "typescript": "^6.0.3",
     "unicode-emoji-json": "^0.9.0",
-    "vitest": "^3.1.4"
+    "vitest": "^4.1.10"
   },
   "license": "MIT",
   "publishConfig": {
@@ -66,7 +70,7 @@
   "scripts": {
     "generate:data": "node scripts/generate-lucide-data.mjs && node scripts/generate-emoji-data.mjs",
     "prebuild": "pnpm generate:data",
-    "build": "tsup src/index.ts src/server.ts --format esm --dts --clean && pnpm build:runtime",
+    "build": "tsup src/index.ts src/server.ts src/host.ts --format esm --dts --clean && pnpm build:runtime",
     "build:runtime": "tsup --config tsup.runtime.ts",
     "test": "vitest run",
     "test:watch": "vitest",