@mindstudio-ai/agent 0.1.20 → 0.1.22

package/dist/index.d.ts

@@ -612,6 +612,17 @@ interface TableConfig {
      * (which need @@user@@ prefix handling) and for validation.
      */
     columns: AppDatabaseColumnSchema[];
+    /**
+     * Unique constraints declared via defineTable options.
+     * Each entry is an array of column names that form a unique constraint.
+     * e.g. [['email'], ['userId', 'orgId']]
+     */
+    unique?: string[][];
+    /**
+     * Default values for columns, applied client-side in push() and upsert().
+     * Explicit values in the input override defaults.
+     */
+    defaults?: Record<string, unknown>;
     /**
      * Execute one or more SQL queries against the managed database in a
      * single round trip. All queries run on the same SQLite connection,
@@ -716,6 +727,7 @@ declare class Query<T> implements PromiseLike<T[]> {
      */
     static _processResults<T>(result: SqlResult, compiled: CompiledQuery<T>): T[];
     then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult2 = never>(onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<T[] | TResult2>;
     private _execute;
     private _compilePredicates;
     private _fetchAndFilterInJs;
@@ -794,6 +806,7 @@ declare class Mutation<TResult> implements PromiseLike<TResult> {
      */
     static fromExecutor<T>(config: TableConfig, executor: () => Promise<T>): Mutation<T>;
     then<T1 = TResult, T2 = never>(onfulfilled?: ((value: TResult) => T1 | PromiseLike<T1>) | null, onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<T1 | T2>;
+    catch<T2 = never>(onrejected?: ((reason: unknown) => T2 | PromiseLike<T2>) | null): Promise<TResult | T2>;
     /**
      * @internal Compile this mutation into SQL for batch execution.
      * Returns the queries and a result processor.
@@ -859,6 +872,20 @@ declare class Table<T> {
      */
     removeAll(predicate: Predicate<T>): Mutation<number>;
     clear(): Mutation<void>;
+    /**
+     * Insert a row, or update it if a row with the same unique key already
+     * exists. The conflict key must match a `unique` constraint declared in
+     * defineTable options. Returns the created or updated row.
+     *
+     * Uses SQLite's `INSERT ... ON CONFLICT ... DO UPDATE SET ... RETURNING *`.
+     *
+     * @param conflictKey - Column name(s) that form the unique constraint.
+     *   Pass a single string for single-column unique, or an array for compound.
+     * @param data - Row data to insert (or update on conflict). Defaults apply.
+     */
+    upsert(conflictKey: (keyof Omit<T, SystemFields> & string) | (keyof Omit<T, SystemFields> & string)[], data: PushInput<T>): Mutation<T>;
+    /** @internal Validate that the given columns match a declared unique constraint. */
+    private _validateUniqueConstraint;
 }
 
 /**
@@ -912,7 +939,7 @@ declare class Table<T> {
 /**
  * Options for `db.defineTable()`.
  */
-interface DefineTableOptions {
+interface DefineTableOptions<T = unknown> {
     /**
      * Database name or ID to target. Required when the app has multiple
      * databases and the table name alone is ambiguous.
@@ -925,6 +952,39 @@ interface DefineTableOptions {
      * - Multiple databases → searched by table name
      */
     database?: string;
+    /**
+     * Unique constraints for the table. Each entry is an array of column
+     * names that together must be unique. The SDK communicates these to
+     * the platform which creates the corresponding SQLite UNIQUE indexes.
+     *
+     * Required for `upsert()` — the conflict key must match a declared
+     * unique constraint.
+     *
+     * @example
+     * ```ts
+     * // Single column unique
+     * db.defineTable<User>('users', { unique: [['email']] });
+     *
+     * // Compound unique
+     * db.defineTable<Membership>('memberships', { unique: [['userId', 'orgId']] });
+     *
+     * // Multiple constraints
+     * db.defineTable<User>('users', { unique: [['email'], ['slug']] });
+     * ```
+     */
+    unique?: (keyof T & string)[][];
+    /**
+     * Default values for columns, applied client-side in `push()` and
+     * `upsert()`. Explicit values in the input override defaults.
+     *
+     * @example
+     * ```ts
+     * db.defineTable<Order>('orders', {
+     *   defaults: { status: 'pending', retryCount: 0 },
+     * });
+     * ```
+     */
+    defaults?: Partial<Omit<T, SystemFields>>;
 }
 
 /**
@@ -955,7 +1015,7 @@ interface Db {
      * const Orders = db.defineTable<Order>('orders', { database: 'main' });
      * ```
      */
-    defineTable<T>(name: string, options?: DefineTableOptions): Table<T & SystemColumns>;
+    defineTable<T>(name: string, options?: DefineTableOptions<T>): Table<T & SystemColumns>;
     /** Returns the current time as a unix timestamp (ms). Equivalent to `Date.now()`. */
     now(): number;
     /** Returns milliseconds for n days. Composable with `+`. */
@@ -2506,10 +2566,7 @@ interface FetchYoutubeChannelStepInput {
     /** YouTube channel URL (e.g. https://www.youtube.com/@ChannelName or /channel/ID) */
     channelUrl: string;
 }
-interface FetchYoutubeChannelStepOutput {
-    /** Channel metadata and video listings */
-    channel: Record<string, unknown>;
-}
+type FetchYoutubeChannelStepOutput = Record<string, unknown>;
 interface FetchYoutubeCommentsStepInput {
     /** YouTube video URL to fetch comments for */
     videoUrl: string;
@@ -2545,10 +2602,7 @@ interface FetchYoutubeVideoStepInput {
     /** YouTube video URL to fetch metadata for */
     videoUrl: string;
 }
-interface FetchYoutubeVideoStepOutput {
-    /** Video metadata including title, description, stats, and channel info */
-    video: Record<string, unknown>;
-}
+type FetchYoutubeVideoStepOutput = Record<string, unknown>;
 interface GenerateChartStepInput {
     /** Chart configuration including type, data, and rendering options */
     chart: {
@@ -4318,10 +4372,7 @@ interface SearchYoutubeTrendsStepInput {
     /** Country code (e.g. "US") */
     gl: string;
 }
-interface SearchYoutubeTrendsStepOutput {
-    /** Trending video data for the selected category and region */
-    trends: Record<string, unknown>;
-}
+type SearchYoutubeTrendsStepOutput = Record<string, unknown>;
 interface SendEmailStepInput {
     /** Email subject line */
     subject: string;

package/dist/index.js

@@ -297,6 +297,18 @@ function buildUpdate(table, id, data, columns) {
     params
   };
 }
+function buildUpsert(table, data, conflictColumns, columns) {
+  const filtered = stripSystemColumns(data);
+  const keys = Object.keys(filtered);
+  const placeholders = keys.map(() => "?").join(", ");
+  const params = keys.map(
+    (k) => serializeColumnParam(filtered[k], k, columns)
+  );
+  const updateKeys = keys.filter((k) => !conflictColumns.includes(k));
+  const conflict = conflictColumns.join(", ");
+  const sql = updateKeys.length > 0 ? `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders}) ON CONFLICT(${conflict}) DO UPDATE SET ${updateKeys.map((k) => `${k} = excluded.${k}`).join(", ")} RETURNING *` : `INSERT INTO ${table} (${keys.join(", ")}) VALUES (${placeholders}) ON CONFLICT(${conflict}) DO NOTHING RETURNING *`;
+  return { sql, params };
+}
 function buildDelete(table, where, whereParams) {
   let sql = `DELETE FROM ${table}`;
   if (where) sql += ` WHERE ${where}`;
@@ -1006,6 +1018,9 @@ var Query = class _Query {
   then(onfulfilled, onrejected) {
     return this._execute().then(onfulfilled, onrejected);
   }
+  catch(onrejected) {
+    return this._execute().catch(onrejected);
+  }
   // -------------------------------------------------------------------------
   // Execution internals
   // -------------------------------------------------------------------------
@@ -1121,6 +1136,9 @@ var Mutation = class _Mutation {
   then(onfulfilled, onrejected) {
     return this._execute().then(onfulfilled, onrejected);
   }
+  catch(onrejected) {
+    return this._execute().catch(onrejected);
+  }
   // -------------------------------------------------------------------------
   // Batch compilation — used by db.batch()
   // -------------------------------------------------------------------------
@@ -1227,7 +1245,9 @@ var Table = class {
   }
   push(data) {
     const isArray = Array.isArray(data);
-    const items = isArray ? data : [data];
+    const items = (isArray ? data : [data]).map(
+      (item) => this._config.defaults ? { ...this._config.defaults, ...item } : item
+    );
     const queries = items.map(
       (item) => buildInsert(
         this._config.tableName,
@@ -1306,6 +1326,60 @@ var Table = class {
     const query = buildDelete(this._config.tableName);
     return new Mutation(this._config, [query], () => void 0);
   }
+  /**
+   * Insert a row, or update it if a row with the same unique key already
+   * exists. The conflict key must match a `unique` constraint declared in
+   * defineTable options. Returns the created or updated row.
+   *
+   * Uses SQLite's `INSERT ... ON CONFLICT ... DO UPDATE SET ... RETURNING *`.
+   *
+   * @param conflictKey - Column name(s) that form the unique constraint.
+   *   Pass a single string for single-column unique, or an array for compound.
+   * @param data - Row data to insert (or update on conflict). Defaults apply.
+   */
+  upsert(conflictKey, data) {
+    const conflictColumns = Array.isArray(conflictKey) ? conflictKey : [conflictKey];
+    this._validateUniqueConstraint(conflictColumns);
+    const withDefaults = this._config.defaults ? { ...this._config.defaults, ...data } : data;
+    const query = buildUpsert(
+      this._config.tableName,
+      withDefaults,
+      conflictColumns,
+      this._config.columns
+    );
+    return new Mutation(
+      this._config,
+      [query],
+      (results) => deserializeRow(
+        results[0].rows[0],
+        this._config.columns
+      )
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+  /** @internal Validate that the given columns match a declared unique constraint. */
+  _validateUniqueConstraint(columns) {
+    if (!this._config.unique?.length) {
+      throw new MindStudioError(
+        `Cannot upsert on ${this._config.tableName}: no unique constraints declared. Add unique: [[${columns.map((c) => `'${c}'`).join(", ")}]] to defineTable options.`,
+        "no_unique_constraint",
+        400
+      );
+    }
+    const sorted = [...columns].sort().join(",");
+    const match = this._config.unique.some(
+      (u) => [...u].sort().join(",") === sorted
+    );
+    if (!match) {
+      throw new MindStudioError(
+        `Cannot upsert on (${columns.join(", ")}): no matching unique constraint declared on ${this._config.tableName}.`,
+        "no_unique_constraint",
+        400
+      );
+    }
+  }
 };
 
 // src/db/index.ts
@@ -1317,6 +1391,8 @@ function createDb(databases, executeBatch) {
         databaseId: resolved.databaseId,
         tableName: name,
         columns: resolved.columns,
+        unique: options?.unique,
+        defaults: options?.defaults,
         executeBatch: (queries) => executeBatch(resolved.databaseId, queries)
       };
       return new Table(config);
@@ -2516,6 +2592,8 @@ var MindStudioAgent = class {
           databaseId: "",
           tableName: name,
           columns: [],
+          unique: options?.unique,
+          defaults: options?.defaults,
           executeBatch: async (queries) => {
             await agent.ensureContext();
             const databases = agent._context.databases;
@@ -2754,9 +2832,9 @@ var monacoSnippets = {
   "fetchGoogleSheet": { fields: [["spreadsheetId", "string"], ["range", "string"], ["exportType", ["csv", "json"]]], outputKeys: ["content"] },
   "fetchSlackChannelHistory": { fields: [["channelId", "string"]], outputKeys: ["messages"] },
   "fetchYoutubeCaptions": { fields: [["videoUrl", "string"], ["exportType", ["text", "json"]], ["language", "string"]], outputKeys: ["transcripts"] },
-  "fetchYoutubeChannel": { fields: [["channelUrl", "string"]], outputKeys: ["channel"] },
+  "fetchYoutubeChannel": { fields: [["channelUrl", "string"]], outputKeys: [] },
   "fetchYoutubeComments": { fields: [["videoUrl", "string"], ["exportType", ["text", "json"]], ["limitPages", "string"]], outputKeys: ["comments"] },
-  "fetchYoutubeVideo": { fields: [["videoUrl", "string"]], outputKeys: ["video"] },
+  "fetchYoutubeVideo": { fields: [["videoUrl", "string"]], outputKeys: [] },
   "generateAsset": { fields: [["source", "string"], ["sourceType", ["html", "markdown", "spa", "raw", "dynamic", "customInterface"]], ["outputFormat", ["pdf", "png", "html", "mp4", "openGraph"]], ["pageSize", ["full", "letter", "A4", "custom"]], ["testData", "object"]], outputKeys: ["url"] },
   "generateChart": { fields: [["chart", "object"]], outputKeys: ["chartUrl"] },
   "generateImage": { fields: [["prompt", "string"]], outputKeys: ["imageUrl"] },
@@ -2840,7 +2918,7 @@ var monacoSnippets = {
   "searchPerplexity": { fields: [["query", "string"], ["exportType", ["text", "json"]]], outputKeys: ["results"] },
   "searchXPosts": { fields: [["query", "string"], ["scope", ["recent", "all"]], ["options", "object"]], outputKeys: ["posts"] },
   "searchYoutube": { fields: [["query", "string"], ["limitPages", "string"], ["filter", "string"], ["filterType", "string"]], outputKeys: ["results"] },
-  "searchYoutubeTrends": { fields: [["bp", ["now", "music", "gaming", "films"]], ["hl", "string"], ["gl", "string"]], outputKeys: ["trends"] },
+  "searchYoutubeTrends": { fields: [["bp", ["now", "music", "gaming", "films"]], ["hl", "string"], ["gl", "string"]], outputKeys: [] },
   "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients"] },
   "sendGmailDraft": { fields: [["draftId", "string"]], outputKeys: [] },
   "sendGmailMessage": { fields: [["to", "string"], ["subject", "string"], ["message", "string"], ["messageType", ["plain", "html", "markdown"]]], outputKeys: ["messageId"] },
@@ -3188,7 +3266,7 @@ var stepMetadata = {
     description: "Retrieve metadata and recent videos for a YouTube channel.",
     usageNotes: "- Accepts a YouTube channel URL (e.g. https://www.youtube.com/@ChannelName or /channel/ID).\n- Returns channel info and video listings as a JSON object.",
     inputSchema: { "type": "object", "properties": { "channelUrl": { "type": "string", "description": "YouTube channel URL (e.g. https://www.youtube.com/@ChannelName or /channel/ID)" } }, "required": ["channelUrl"] },
-    outputSchema: { "type": "object", "properties": { "channel": { "type": "object", "description": "Channel metadata and video listings" } }, "required": ["channel"] }
+    outputSchema: { "type": "object" }
   },
   "fetchYoutubeComments": {
     stepType: "fetchYoutubeComments",
@@ -3202,7 +3280,7 @@ var stepMetadata = {
     description: "Retrieve metadata for a YouTube video (title, description, stats, channel info).",
     usageNotes: "- Returns video metadata, channel info, and engagement stats.\n- Video format data is excluded from the response.",
     inputSchema: { "type": "object", "properties": { "videoUrl": { "type": "string", "description": "YouTube video URL to fetch metadata for" } }, "required": ["videoUrl"] },
-    outputSchema: { "type": "object", "properties": { "video": { "type": "object", "description": "Video metadata including title, description, stats, and channel info" } }, "required": ["video"] }
+    outputSchema: { "type": "object" }
   },
   "generateAsset": {
     stepType: "generatePdf",
@@ -3807,7 +3885,7 @@ var stepMetadata = {
     description: "Retrieve trending videos on YouTube by category and region.",
     usageNotes: '- Categories: "now" (trending now), "music", "gaming", "films".\n- Supports country and language filtering.',
     inputSchema: { "type": "object", "properties": { "bp": { "enum": ["now", "music", "gaming", "films"], "type": "string", "description": 'Trending category: "now" (trending now), "music", "gaming", or "films"' }, "hl": { "type": "string", "description": 'Language code (e.g. "en")' }, "gl": { "type": "string", "description": 'Country code (e.g. "US")' } }, "required": ["bp", "hl", "gl"] },
-    outputSchema: { "type": "object", "properties": { "trends": { "type": "object", "description": "Trending video data for the selected category and region" } }, "required": ["trends"] }
+    outputSchema: { "type": "object" }
   },
   "sendEmail": {
     stepType: "sendEmail",