corsair 0.1.21 → 0.1.22

package/dist/core/inspect/index.d.ts

@@ -1,4 +1,5 @@
 import type { CorsairPlugin } from '../plugins';
+type DbFieldType = 'string' | 'number' | 'boolean' | 'date';
 export type EndpointSchemaResult = {
     /** Human-readable description of what this endpoint does. */
     description?: string;
@@ -34,6 +35,35 @@ export type WebhookSchemaResult = {
      */
     availableWebhooks?: Record<string, string[]>;
 };
+export type DbSearchSchemaResult = {
+    /**
+     * What this entity type represents and how to search it.
+     * Pass `limit` and `offset` as numbers for pagination.
+     */
+    description: string;
+    /**
+     * Filterable fields for the search() call.
+     * All active filters are AND-combined. Omit a field to skip filtering on it.
+     *
+     * Each operator shorthand: passing a raw value (string/number/boolean/Date) is
+     * equivalent to `{ equals: value }`.
+     */
+    filters: {
+        /** Filter by the entity's external platform ID (e.g. a Slack channel ID). */
+        entity_id: {
+            type: 'string';
+            operators: string[];
+        };
+        /**
+         * Filter by fields inside the entity's data payload.
+         * Only flat primitive fields are listed — nested objects are not filterable.
+         */
+        data: Record<string, {
+            type: DbFieldType;
+            operators: string[];
+        }>;
+    };
+};
 export type ListOperationsOptions = {
     /**
      * Filter to a specific plugin by its ID (e.g. 'slack', 'github').
@@ -42,24 +72,29 @@ export type ListOperationsOptions = {
      */
     plugin?: string;
     /**
-     * Whether to list API endpoints or webhooks.
-     * Defaults to 'api' when not provided.
+     * Whether to list API endpoints, webhooks, or database entities.
+     * - 'api' (default) — lists callable API endpoint paths
+     * - 'webhooks' — lists receivable webhook event paths
+     * - 'db' — lists searchable database entity paths (one .search per entity type)
      */
-    type?: 'api' | 'webhooks';
+    type?: 'api' | 'webhooks' | 'db';
 };
 export type CorsairInspectMethods = {
     /**
-     * Lists available operations (API endpoints or webhooks) for the configured plugins.
+     * Lists available operations (API endpoints, webhooks, or database entities) for the configured plugins.
      *
      * - No options → all API endpoint paths across every plugin, keyed by plugin ID
      * - `{ type: 'webhooks' }` → all webhook paths across every plugin, keyed by plugin ID
+     * - `{ type: 'db' }` → all searchable DB entity paths across every plugin, keyed by plugin ID
      * - `{ plugin: 'slack' }` → Slack API endpoint paths as a flat array
      * - `{ plugin: 'slack', type: 'webhooks' }` → Slack webhook paths as a flat array
+     * - `{ plugin: 'slack', type: 'db' }` → Slack DB entity search paths as a flat array
      * - If the plugin is known but not configured, returns a plain string message.
      * - If the plugin string is completely unrecognised, returns all API endpoints (same as no options).
      *
      * API paths use the format `plugin.api.group.method` (e.g. `slack.api.messages.post`).
      * Webhook paths use the format `plugin.webhooks.group.event` (e.g. `slack.webhooks.messages.message`).
+     * DB paths use the format `plugin.db.entityType.search` (e.g. `slack.db.messages.search`).
      * All paths can be passed directly to `get_schema()`.
      *
      * @example
@@ -72,15 +107,19 @@ export type CorsairInspectMethods = {
      * corsair.list_operations({ plugin: 'slack', type: 'webhooks' })
      * // ['slack.webhooks.messages.message', 'slack.webhooks.channels.created', ...]
      *
+     * corsair.list_operations({ plugin: 'slack', type: 'db' })
+     * // ['slack.db.messages.search', 'slack.db.channels.search', 'slack.db.users.search', ...]
+     *
      * corsair.list_operations({ plugin: 'unknown' })
      * // "unknown isn't configured in the Corsair instance."
      */
     list_operations(options?: ListOperationsOptions): Record<string, string[]> | string[] | string;
     /**
-     * Returns schema and metadata for a specific API endpoint or webhook.
+     * Returns schema and metadata for a specific API endpoint, webhook, or database entity search.
      * The path format determines which kind of schema is returned:
      * - API path (`plugin.api.group.method`) → `EndpointSchemaResult`
      * - Webhook path (`plugin.webhooks.group.event`) → `WebhookSchemaResult`
+     * - DB path (`plugin.db.entityType.search`) → `DbSearchSchemaResult`
      *
      * Casing is ignored — the path is lowercased before lookup.
      * If the path is not found, returns an object with available paths for self-correction.
@@ -92,14 +131,18 @@ export type CorsairInspectMethods = {
      * corsair.get_schema('slack.webhooks.messages.message')
      * // { description: '...', usage: '...', payload: { ... }, response: { ... } }
      *
+     * corsair.get_schema('slack.db.messages.search')
+     * // { description: '...', filters: { entity_id: { ... }, data: { text: { type: 'string', operators: [...] }, ... } } }
+     *
      * corsair.get_schema('slack.api.invalid')
      * // { availableMethods: { slack: ['slack.api.channels.list', ...], ... } }
      */
-    get_schema(path: string): EndpointSchemaResult | WebhookSchemaResult;
+    get_schema(path: string): EndpointSchemaResult | WebhookSchemaResult | DbSearchSchemaResult;
 };
 /**
  * Creates the list_operations / get_schema functions bound to a specific plugin list.
  * Used by both single-tenant and multi-tenant client builders.
  */
 export declare function buildInspectMethods(plugins: readonly CorsairPlugin[]): CorsairInspectMethods;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/core/inspect/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/inspect/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAqFnE,MAAM,MAAM,oBAAoB,GAAG;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IAC7C,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,eAAe,CACd,OAAO,CAAC,EAAE,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;IAChD;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;CACrE,CAAC;AA4UF;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,aAAa,EAAE,GAC/B,qBAAqB,CASvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../core/inspect/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AA2FnE,KAAK,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAyF5D,MAAM,MAAM,oBAAoB,GAAG;IAClC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IAC7C,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAClC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,EAAE;QACR,6EAA6E;QAC7E,SAAS,EAAE;YAAE,IAAI,EAAE,QAAQ,CAAC;YAAC,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;QACnD;;;WAGG;QACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,WAAW,CAAC;YAAC,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KACjE,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,eAAe,CACd,OAAO,CAAC,EAAE,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;IAChD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,GACV,oBAAoB,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;CACrE,CAAC;AAmYF;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,aAAa,EAAE,GAC/B,qBAAqB,CASvB"}

package/dist/core/inspect/index.js

@@ -75,6 +75,89 @@ function zodToJsonSchema(schema) {
     }
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// DB Entity Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+const STRING_OPERATORS = ['equals', 'contains', 'startsWith', 'endsWith', 'in'];
+const NUMBER_OPERATORS = ['equals', 'gt', 'gte', 'lt', 'lte', 'in'];
+const BOOLEAN_OPERATORS = ['equals'];
+const DATE_OPERATORS = ['equals', 'before', 'after', 'between'];
+/**
+ * Unwraps Optional/Nullable/Default/Effects wrappers to find the primitive leaf type.
+ * Returns null for complex types (objects, arrays, unions) that are not directly filterable.
+ */
+function getSchemaLeafType(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    switch (typeName) {
+        case 'ZodOptional':
+        case 'ZodNullable':
+        case 'ZodDefault':
+            return getSchemaLeafType(def.innerType);
+        case 'ZodEffects':
+            // Covers z.coerce.date() and other transforms
+            return getSchemaLeafType(def.schema);
+        case 'ZodString':
+            return 'string';
+        case 'ZodNumber':
+            return 'number';
+        case 'ZodBoolean':
+            return 'boolean';
+        case 'ZodDate':
+            return 'date';
+        default:
+            return null;
+    }
+}
+/**
+ * Derives the filterable fields from a Zod object schema.
+ * Only flat primitive fields (string, number, boolean, date) are included.
+ * Nested objects and arrays are skipped — the ORM does not support filtering into them.
+ */
+function buildFilterableFields(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    if (typeName === 'ZodOptional' ||
+        typeName === 'ZodNullable' ||
+        typeName === 'ZodDefault') {
+        return buildFilterableFields(def.innerType);
+    }
+    if (typeName === 'ZodEffects') {
+        return buildFilterableFields(def.schema);
+    }
+    if (typeName !== 'ZodObject')
+        return {};
+    const shape = def.shape();
+    const result = {};
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        const leafType = getSchemaLeafType(fieldSchema);
+        if (leafType === 'string') {
+            result[key] = { type: 'string', operators: STRING_OPERATORS };
+        }
+        else if (leafType === 'number') {
+            result[key] = { type: 'number', operators: NUMBER_OPERATORS };
+        }
+        else if (leafType === 'boolean') {
+            result[key] = { type: 'boolean', operators: BOOLEAN_OPERATORS };
+        }
+        else if (leafType === 'date') {
+            result[key] = { type: 'date', operators: DATE_OPERATORS };
+        }
+        // Nested objects, arrays, unions — not filterable via ORM, omit them
+    }
+    return result;
+}
+/**
+ * Case-insensitive lookup for an entity name in a schema's entities map.
+ * Entity names are camelCase (e.g. 'userGroups') but agent paths are lowercased.
+ */
+function findEntityCaseInsensitive(entities, lowercasedName) {
+    for (const [key, schema] of Object.entries(entities)) {
+        if (key.toLowerCase() === lowercasedName)
+            return [key, schema];
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // Endpoint Tree Walker
 // ─────────────────────────────────────────────────────────────────────────────
 function walkEndpointTree(tree, pathParts, result) {
@@ -222,13 +305,17 @@ function listOperations(plugins, options) {
             walkWebhookTree(found.webhooks, [], paths);
             return paths.map((path) => `${found.id}.webhooks.${path}`);
         }
-        else {
-            if (!found.endpoints)
+        if (type === 'db') {
+            const entities = found.schema?.entities;
+            if (!entities)
                 return [];
-            const paths = [];
-            walkEndpointTree(found.endpoints, [], paths);
-            return paths.map((path) => `${found.id}.api.${path.toLowerCase()}`);
+            return Object.keys(entities).map((entityName) => `${found.id}.db.${entityName}.search`);
         }
+        if (!found.endpoints)
+            return [];
+        const paths = [];
+        walkEndpointTree(found.endpoints, [], paths);
+        return paths.map((path) => `${found.id}.api.${path.toLowerCase()}`);
     }
     const result = {};
     if (type === 'webhooks') {
@@ -240,6 +327,14 @@ function listOperations(plugins, options) {
             result[p.id] = paths.map((path) => `${p.id}.webhooks.${path}`);
         }
     }
+    else if (type === 'db') {
+        for (const p of plugins) {
+            const entities = p.schema?.entities;
+            if (!entities)
+                continue;
+            result[p.id] = Object.keys(entities).map((entityName) => `${p.id}.db.${entityName}.search`);
+        }
+    }
     else {
         for (const p of plugins) {
             if (!p.endpoints)
@@ -274,6 +369,38 @@ function getSchema(plugins, path) {
         const remainder = normalised.slice(dotIndex + 1);
         const plugin = plugins.find((p) => p.id === pluginId);
         if (plugin) {
+            // ── DB search path: plugin.db.entityType.search ────────────────────────
+            if (remainder.startsWith('db.')) {
+                const dbPath = remainder.slice(3); // strip 'db.'
+                const lastDot = dbPath.lastIndexOf('.');
+                if (lastDot !== -1) {
+                    const entityNameLower = dbPath.slice(0, lastDot);
+                    const method = dbPath.slice(lastDot + 1);
+                    const entities = plugin.schema?.entities;
+                    if (method === 'search' && entities) {
+                        const entry = findEntityCaseInsensitive(entities, entityNameLower);
+                        if (entry) {
+                            const [entityName, entitySchema] = entry;
+                            return {
+                                description: `Search ${pluginId} ${entityName} stored in the local database. Returns an array of matching records. Pass limit and offset (numbers) for pagination.`,
+                                filters: {
+                                    entity_id: {
+                                        type: 'string',
+                                        operators: STRING_OPERATORS,
+                                    },
+                                    data: buildFilterableFields(entitySchema),
+                                },
+                            };
+                        }
+                    }
+                }
+                // Invalid db path — return available db operations for self-correction
+                return {
+                    availableMethods: listOperations(plugins, {
+                        type: 'db',
+                    }),
+                };
+            }
             // ── Webhook path: plugin.webhooks.group.event ──────────────────────────
             if (remainder.startsWith('webhooks.')) {
                 const webhookPathNormalised = remainder.slice(9); // strip 'webhooks.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "corsair",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",