@plotday/twister 0.27.0 → 0.29.0

package/dist/tool.js

@@ -110,13 +110,16 @@ export class Tool {
      * @param args - Optional arguments to pass to the callback
      * @returns Promise resolving to the callback result
      */
-    async run(token, args) {
-        return this.tools.callbacks.run(token, args);
+    async run(token, ...args) {
+        return this.tools.callbacks.run(token, ...args);
     }
     /**
      * Retrieves a value from persistent storage by key.
      *
-     * @template T - The expected type of the stored value
+     * Values are automatically deserialized using SuperJSON, which
+     * properly restores Date objects, Maps, Sets, and other complex types.
+     *
+     * @template T - The expected type of the stored value (must be Serializable)
      * @param key - The storage key to retrieve
      * @returns Promise resolving to the stored value or null
      */
@@ -126,13 +129,32 @@ export class Tool {
     /**
      * Stores a value in persistent storage.
      *
-     * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values
-     * cannot be stored directly.
+     * The value will be serialized using SuperJSON and stored persistently.
+     * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+     * and other complex types that standard JSON doesn't support.
      *
+     * **Important**: Functions and Symbols cannot be stored.
      * **For function references**: Use callbacks instead of storing functions directly.
      *
      * @example
      * ```typescript
+     * // ✅ Date objects are preserved
+     * await this.set("sync_state", {
+     *   lastSync: new Date(),
+     *   minDate: new Date(2024, 0, 1)
+     * });
+     *
+     * // ✅ undefined is now supported
+     * await this.set("data", { name: "test", optional: undefined });
+     *
+     * // ✅ Arrays with undefined are supported
+     * await this.set("items", [1, undefined, 3]);
+     * await this.set("items", [1, null, 3]); // Also works
+     *
+     * // ✅ Maps and Sets are supported
+     * await this.set("mapping", new Map([["key", "value"]]));
+     * await this.set("tags", new Set(["tag1", "tag2"]));
+     *
      * // ❌ WRONG: Cannot store functions directly
      * await this.set("handler", this.myHandler);
      *
@@ -145,9 +167,9 @@ export class Tool {
      * await this.run(token, args);
      * ```
      *
-     * @template T - The type of value being stored
+     * @template T - The type of value being stored (must be Serializable)
      * @param key - The storage key to use
-     * @param value - The value to store (must be JSON-serializable)
+     * @param value - The value to store (must be SuperJSON-serializable)
      * @returns Promise that resolves when the value is stored
      */
     async set(key, value) {

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/network.d.ts

@@ -1,5 +1,6 @@
 import { ITool } from "..";
 import { type AuthProvider, type Authorization } from "./integrations";
+import { type NoFunctions, type JSONValue } from "../utils/types";
 /**
  * Represents an incoming webhook request.
  *
@@ -25,7 +26,7 @@ export type WebhookRequest = {
     /** Query string parameters from the request URL */
     params: Record<string, string>;
     /** Request body (parsed as JSON if applicable) */
-    body: any;
+    body: JSONValue;
     /** Raw request body (for signature verification) */
     rawBody?: string;
 };
@@ -82,10 +83,12 @@ export type WebhookRequest = {
  *
  *   async setupCalendarWebhook(calendarId: string) {
  *     // Create webhook URL that will call onCalendarEvent
- *     const webhookUrl = await this.tools.network.createWebhook({
- *       callback: this.onCalendarEvent,
- *       extraArgs: [calendarId, "google"]
- *     });
+ *     const webhookUrl = await this.tools.network.createWebhook(
+ *       {},
+ *       this.onCalendarEvent,
+ *       calendarId,
+ *       "google"
+ *     );
  *
  *     // Register webhook with Google Calendar API
  *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);
@@ -133,21 +136,23 @@ export declare abstract class Network extends ITool {
      * - **Default**: Returns a standard webhook URL for all other cases.
      *
      * @param options - Webhook creation options
-     * @param options.callback - Function receiving (request, ...extraArgs)
-     * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)
      * @param options.provider - Optional provider for provider-specific webhook routing
      * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)
+     * @param callback - Function receiving (request, ...extraArgs)
+     * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
      * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name
      *
      * @example
      * ```typescript
      * // Gmail webhook - returns Pub/Sub topic name
-     * const topicName = await this.tools.network.createWebhook({
-     *   callback: this.onGmailNotification,
-     *   provider: AuthProvider.Google,
-     *   authorization: gmailAuth,
-     *   extraArgs: ["inbox"]
-     * });
+     * const topicName = await this.tools.network.createWebhook(
+     *   {
+     *     provider: AuthProvider.Google,
+     *     authorization: gmailAuth
+     *   },
+     *   this.onGmailNotification,
+     *   "inbox"
+     * );
      * // topicName: "projects/plot-prod/topics/gmail-webhook-abc123"
      *
      * // Pass topic name to Gmail API
@@ -161,11 +166,9 @@ export declare abstract class Network extends ITool {
      * ```
      */
     abstract createWebhook<TCallback extends (request: WebhookRequest, ...args: any[]) => any>(options: {
-        callback: TCallback;
-        extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];
         provider?: AuthProvider;
         authorization?: Authorization;
-    }): Promise<string>;
+    }, callback: TCallback, ...extraArgs: TCallback extends (req: any, ...rest: infer R) => any ? NoFunctions<R> : []): Promise<string>;
     /**
      * Deletes an existing webhook endpoint.
      *

package/dist/tools/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/tools/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,IAAI,EAAE,GAAG,CAAC;IACV,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IACzC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QACvB;;;WAGG;QACH,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,QAAQ,CAAC,aAAa,CACpB,SAAS,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAClE,OAAO,EAAE;QACT,QAAQ,EAAE,SAAS,CAAC;QACpB,SAAS,CAAC,EAAE,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QAC3E,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnB;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CACnD"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/tools/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IACzC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QACvB;;;WAGG;QACH,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,QAAQ,CAAC,aAAa,CACpB,SAAS,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAElE,OAAO,EAAE;QACP,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B,EACD,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAC/D,WAAW,CAAC,CAAC,CAAC,GACd,EAAE,GACL,OAAO,CAAC,MAAM,CAAC;IAElB;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CACnD"}

package/dist/tools/network.js

@@ -52,10 +52,12 @@ import { ITool } from "..";
  *
  *   async setupCalendarWebhook(calendarId: string) {
  *     // Create webhook URL that will call onCalendarEvent
- *     const webhookUrl = await this.tools.network.createWebhook({
- *       callback: this.onCalendarEvent,
- *       extraArgs: [calendarId, "google"]
- *     });
+ *     const webhookUrl = await this.tools.network.createWebhook(
+ *       {},
+ *       this.onCalendarEvent,
+ *       calendarId,
+ *       "google"
+ *     );
  *
  *     // Register webhook with Google Calendar API
  *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);

package/dist/tools/network.js.map

@@ -1 +1 @@
-{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/tools/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAiC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,MAAM,OAAgB,OAAQ,SAAQ,KAAK;IACzC,MAAM,CAAU,OAAO,CAMrB;CAwEH"}
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/tools/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAkC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,OAAgB,OAAQ,SAAQ,KAAK;IACzC,MAAM,CAAU,OAAO,CAMrB;CA8EH"}

package/dist/tools/plot.d.ts

@@ -1,4 +1,4 @@
-import { type Activity, type ActivityMeta, type ActivityUpdate, type Actor, type ActorId, ITool, type NewActivity, type NewActivityWithNotes, type NewContact, type NewNote, type NewPriority, type Note, type NoteUpdate, type Priority, type Tag } from "..";
+import { type Activity, type ActivityUpdate, type Actor, type ActorId, ITool, type NewActivity, type NewActivityWithNotes, type NewContact, type NewNote, type NewPriority, type Note, type NoteUpdate, type Priority, type PriorityUpdate, type Tag, Uuid } from "..";
 export declare enum ActivityAccess {
     /**
      * Create new Note on an Activity where the twist was mentioned.
@@ -26,7 +26,7 @@ export declare enum PriorityAccess {
     Full = 1
 }
 export declare enum ContactAccess {
-    /** Read existing contacts. */
+    /** Read existing contact details. Without this, only the ID will be provided. */
     Read = 0,
     /** Create and update contacts. */
     Write = 1
@@ -76,10 +76,56 @@ export type NoteIntentHandler = {
  * ```
  */
 export declare abstract class Plot extends ITool {
+    /**
+     * Configuration options for the Plot tool.
+     *
+     * **Important**: All permissions must be explicitly requested. There are no default permissions.
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with required permissions
+     * build(build: ToolBuilder) {
+     *   return {
+     *     plot: build(Plot, {
+     *       activity: {
+     *         access: ActivityAccess.Create
+     *       }
+     *     })
+     *   };
+     * }
+     *
+     * // Full configuration with callbacks
+     * build(build: ToolBuilder) {
+     *   return {
+     *     plot: build(Plot, {
+     *       activity: {
+     *         access: ActivityAccess.Create,
+     *         updated: this.onActivityUpdated
+     *       },
+     *       note: {
+     *         intents: [{
+     *           description: "Schedule meetings",
+     *           examples: ["Schedule a meeting tomorrow"],
+     *           handler: this.onSchedulingIntent
+     *         }],
+     *         created: this.onNoteCreated
+     *       },
+     *       priority: {
+     *         access: PriorityAccess.Full
+     *       },
+     *       contact: {
+     *         access: ContactAccess.Write
+     *       }
+     *     })
+     *   };
+     * }
+     * ```
+     */
     static readonly Options: {
         activity?: {
             /**
              * Capability to create Notes and modify tags.
+             * Must be explicitly set to grant permissions.
              */
             access?: ActivityAccess;
             /**
@@ -182,7 +228,7 @@ export declare abstract class Plot extends ITool {
      * // Mark a task as complete
      * await this.plot.updateActivity({
      *   id: "task-123",
-     *   doneAt: new Date()
+     *   done: new Date()
      * });
      *
      * // Reschedule an event
@@ -308,35 +354,35 @@ export declare abstract class Plot extends ITool {
      */
     abstract updateNote(note: NoteUpdate): Promise<void>;
     /**
-     * Finds an activity by its meta.source.
-     *
-     * This method enables lookup of activities that were created from external
-     * systems, using the metadata to locate the corresponding Plot activity.
+     * Retrieves an activity by ID or source.
      *
-     * By default, archived activities are excluded from the search. Set includeArchived
-     * to true to include them in the results.
+     * This method enables lookup of activities either by their unique ID or by their
+     * source identifier (canonical URL from an external system). Archived activities
+     * are included in the results.
      *
-     * @param source - The meta.source value to search for
-     * @param includeArchived - Whether to include archived activities in search (default: false)
+     * @param activity - Activity lookup by ID or source
      * @returns Promise resolving to the matching activity or null if not found
      */
-    abstract getActivityBySource(source: string, includeArchived?: boolean): Promise<Activity | null>;
+    abstract getActivity(activity: {
+        id: Uuid;
+    } | {
+        source: string;
+    }): Promise<Activity | null>;
     /**
-     * Finds an activity by its metadata.
+     * Retrieves a note by ID or key.
      *
-     * This method enables lookup of activities that were created from external
-     * systems, using the metadata to locate the corresponding Plot activity.
-     * Uses JSON containment matching - the provided meta must be contained
-     * within the activity's meta field.
+     * This method enables lookup of notes either by their unique ID or by their
+     * key (unique identifier within the activity). Archived notes are included
+     * in the results.
      *
-     * By default, archived activities are excluded from the search. Set includeArchived
-     * to true to include them in the results.
-     *
-     * @param meta - The metadata to search for (uses JSON containment matching)
-     * @param includeArchived - Whether to include archived activities in search (default: false)
-     * @returns Promise resolving to the matching activity or null if not found
+     * @param note - Note lookup by ID or key
+     * @returns Promise resolving to the matching note or null if not found
      */
-    abstract getActivityByMeta(meta: ActivityMeta, includeArchived?: boolean): Promise<Activity | null>;
+    abstract getNote(note: {
+        id: Uuid;
+    } | {
+        key: string;
+    }): Promise<Note | null>;
     /**
      * Creates a new priority in the Plot system.
      *
@@ -347,6 +393,29 @@ export declare abstract class Plot extends ITool {
      * @returns Promise resolving to the complete created priority
      */
     abstract createPriority(priority: NewPriority): Promise<Priority>;
+    /**
+     * Retrieves a priority by ID or key.
+     *
+     * Archived priorities are included in the results.
+     *
+     * @param priority - Priority lookup by ID or key
+     * @returns Promise resolving to the matching priority or null if not found
+     */
+    abstract getPriority(priority: {
+        id: Uuid;
+    } | {
+        key: string;
+    }): Promise<Priority | null>;
+    /**
+     * Updates an existing priority in the Plot system.
+     *
+     * The priority is identified by either its ID or key.
+     * Only the fields specified in the update will be changed.
+     *
+     * @param update - Priority update containing ID/key and fields to change
+     * @returns Promise that resolves when the update is complete
+     */
+    abstract updatePriority(update: PriorityUpdate): Promise<void>;
     /**
      * Adds contacts to the Plot system.
      *

package/dist/tools/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"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"}

package/dist/tools/plot.js

@@ -29,7 +29,7 @@ export var PriorityAccess;
 })(PriorityAccess || (PriorityAccess = {}));
 export var ContactAccess;
 (function (ContactAccess) {
-    /** Read existing contacts. */
+    /** Read existing contact details. Without this, only the ID will be provided. */
     ContactAccess[ContactAccess["Read"] = 0] = "Read";
     /** Create and update contacts. */
     ContactAccess[ContactAccess["Write"] = 1] = "Write";
@@ -67,6 +67,51 @@ export var ContactAccess;
  * ```
  */
 export class Plot extends ITool {
+    /**
+     * Configuration options for the Plot tool.
+     *
+     * **Important**: All permissions must be explicitly requested. There are no default permissions.
+     *
+     * @example
+     * ```typescript
+     * // Minimal configuration with required permissions
+     * build(build: ToolBuilder) {
+     *   return {
+     *     plot: build(Plot, {
+     *       activity: {
+     *         access: ActivityAccess.Create
+     *       }
+     *     })
+     *   };
+     * }
+     *
+     * // Full configuration with callbacks
+     * build(build: ToolBuilder) {
+     *   return {
+     *     plot: build(Plot, {
+     *       activity: {
+     *         access: ActivityAccess.Create,
+     *         updated: this.onActivityUpdated
+     *       },
+     *       note: {
+     *         intents: [{
+     *           description: "Schedule meetings",
+     *           examples: ["Schedule a meeting tomorrow"],
+     *           handler: this.onSchedulingIntent
+     *         }],
+     *         created: this.onNoteCreated
+     *       },
+     *       priority: {
+     *         access: PriorityAccess.Full
+     *       },
+     *       contact: {
+     *         access: ContactAccess.Write
+     *       }
+     *     })
+     *   };
+     * }
+     * ```
+     */
     static Options;
 }
 //# sourceMappingURL=plot.js.map

package/dist/tools/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,GAUN,MAAM,IAAI,CAAC;AAEZ,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,yDAAO,CAAA;IACP;;;;OAIG;IACH,uDAAM,CAAA;AACR,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAM,CAAA;IACN;;;;OAIG;IACH,mDAAI,CAAA;AACN,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACvB,8BAA8B;IAC9B,iDAAI,CAAA;IACJ,kCAAkC;IAClC,mDAAK,CAAA;AACP,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAgB,IAAK,SAAQ,KAAK;IACtC,MAAM,CAAU,OAAO,CA8DrB;CA4QH"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,GAYN,MAAM,IAAI,CAAC;AAEZ,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,yDAAO,CAAA;IACP;;;;OAIG;IACH,uDAAM,CAAA;AACR,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAM,CAAA;IACN;;;;OAIG;IACH,mDAAI,CAAA;AACN,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACvB,iFAAiF;IACjF,iDAAI,CAAA;IACJ,kCAAkC;IAClC,mDAAK,CAAA;AACP,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAgB,IAAK,SAAQ,KAAK;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,MAAM,CAAU,OAAO,CA+DrB;CAyRH"}

package/dist/tools/store.d.ts

@@ -1,4 +1,4 @@
-import { ITool } from "..";
+import { ITool, type Serializable } from "..";
 /**
  * Built-in tool for persistent key-value storage.
  *
@@ -13,9 +13,20 @@ import { ITool } from "..";
  * **Storage Characteristics:**
  * - Persistent across worker restarts
  * - Isolated per twist/tool instance
- * - Supports any JSON-serializable data
+ * - Supports SuperJSON-serializable data (see below)
  * - Async operations for scalability
  *
+ * **Supported Data Types (via SuperJSON):**
+ * - Primitives: string, number, boolean, null, undefined
+ * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt
+ * - Collections: Arrays and objects (recursively)
+ *
+ * **NOT Supported (will throw validation errors):**
+ * - Functions (use callback tokens instead - see Callbacks tool)
+ * - Symbols
+ * - Circular references
+ * - Custom class instances
+ *
  * **Use Cases:**
  * - Storing authentication tokens
  * - Caching configuration data
@@ -50,23 +61,53 @@ export declare abstract class Store extends ITool {
      * Returns the stored value deserialized to the specified type,
      * or null if the key doesn't exist or the value is null.
      *
-     * @template T - The expected type of the stored value
+     * Values are automatically deserialized using SuperJSON, which
+     * properly restores Date objects, Maps, Sets, and other complex types.
+     *
+     * @template T - The expected type of the stored value (must be Serializable)
      * @param key - The storage key to retrieve
      * @returns Promise resolving to the stored value or null
      */
-    abstract get<T>(key: string): Promise<T | null>;
+    abstract get<T extends Serializable>(key: string): Promise<T | null>;
     /**
      * Stores a value in persistent storage.
      *
-     * The value will be JSON-serialized and stored persistently.
+     * The value will be serialized using SuperJSON and stored persistently.
      * Any existing value at the same key will be overwritten.
      *
-     * @template T - The type of value being stored
+     * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+     * and other complex types that standard JSON doesn't support.
+     *
+     * @template T - The type of value being stored (must be Serializable)
      * @param key - The storage key to use
-     * @param value - The value to store (must be JSON-serializable)
+     * @param value - The value to store (must be SuperJSON-serializable)
      * @returns Promise that resolves when the value is stored
+     *
+     * @example
+     * ```typescript
+     * // Date objects are preserved
+     * await this.set('sync_state', {
+     *   lastSync: new Date(),
+     *   minDate: new Date(2024, 0, 1)
+     * });
+     *
+     * // undefined is now supported
+     * await this.set('data', { name: 'test', optional: undefined }); // ✅ Works
+     *
+     * // Arrays with undefined are supported
+     * await this.set('items', [1, undefined, 3]); // ✅ Works
+     * await this.set('items', [1, null, 3]); // ✅ Also works
+     *
+     * // Maps and Sets are supported
+     * await this.set('mapping', new Map([['key', 'value']])); // ✅ Works
+     * await this.set('tags', new Set(['tag1', 'tag2'])); // ✅ Works
+     *
+     * // Functions are NOT supported - use callback tokens instead
+     * const token = await this.callback(this.myFunction);
+     * await this.set('callback_ref', token); // ✅ Use callback token
+     * ```
      */
-    abstract set<T>(key: string, value: T): Promise<void>;
+    abstract set<T extends Serializable>(key: string, value: T): Promise<void>;
     /**
      * Removes a specific key from storage.
      *

package/dist/tools/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;OASG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;OAUG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAErD;;;;;;;;OAQG;IAEH,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CACnC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,IAAI,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;;;;OAYG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;;;;;;;OAQG;IAEH,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CACnC"}

package/dist/tools/store.js

@@ -13,9 +13,20 @@ import { ITool } from "..";
  * **Storage Characteristics:**
  * - Persistent across worker restarts
  * - Isolated per twist/tool instance
- * - Supports any JSON-serializable data
+ * - Supports SuperJSON-serializable data (see below)
  * - Async operations for scalability
  *
+ * **Supported Data Types (via SuperJSON):**
+ * - Primitives: string, number, boolean, null, undefined
+ * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt
+ * - Collections: Arrays and objects (recursively)
+ *
+ * **NOT Supported (will throw validation errors):**
+ * - Functions (use callback tokens instead - see Callbacks tool)
+ * - Symbols
+ * - Circular references
+ * - Custom class instances
+ *
  * **Use Cases:**
  * - Storing authentication tokens
  * - Caching configuration data

package/dist/tools/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CAiDxC"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,IAAI,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CA+ExC"}

package/dist/tools/tasks.d.ts

@@ -3,12 +3,12 @@ import type { Callback } from "./callbacks";
 /**
  * Run background tasks and scheduled jobs.
  *
- * The Run tool enables twists and tools to queue callbacks. This is especially
- * iportant for long-running operations and batch processing, since twists
- * operate within runtime limits. Run callbacks also benefit from automatic
+ * The Tasks tool enables twists and tools to queue callbacks. This is especially
+ * important for long-running operations and batch processing, since twists
+ * operate within runtime limits. Task callbacks also benefit from automatic
  * retries on failure.
  *
- * **Note:** Run methods are also available directly on Twist and Tool classes
+ * **Note:** Tasks tool methods are also available directly on Twist and Tool classes
  * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.
  * This is the recommended approach for most use cases.
  *

package/dist/tools/tasks.js

@@ -2,12 +2,12 @@ import { ITool } from "..";
 /**
  * Run background tasks and scheduled jobs.
  *
- * The Run tool enables twists and tools to queue callbacks. This is especially
- * iportant for long-running operations and batch processing, since twists
- * operate within runtime limits. Run callbacks also benefit from automatic
+ * The Tasks tool enables twists and tools to queue callbacks. This is especially
+ * important for long-running operations and batch processing, since twists
+ * operate within runtime limits. Task callbacks also benefit from automatic
  * retries on failure.
  *
- * **Note:** Run methods are also available directly on Twist and Tool classes
+ * **Note:** Tasks tool methods are also available directly on Twist and Tool classes
  * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.
  * This is the recommended approach for most use cases.
  *