Cleanup in preparation for stable 1.0 release

Author: KrisBraun

.changeset/kind-flowers-mate.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Minor type and signature changes in preparation for the stable 1.0 interface

.changeset/salty-pigs-bathe.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": patch
+---
+
+Added: archived field on Priority, Activity, and Note

twister/src/common/calendar.ts

@@ -1,4 +1,5 @@
 import type { ActivityLink, NewActivityWithNotes, SyncUpdate } from "../index";
+import type { NoFunctions } from "../utils/types";
 
 /**
  * Represents successful calendar authorization.
@@ -86,9 +87,12 @@ export interface SyncOptions {
  *     const primaryCalendar = calendars.find(c => c.primary);
  *     if (primaryCalendar) {
  *       await this.googleCalendar.startSync(
- *         auth.authToken,
- *         primaryCalendar.id,
- *         "onCalendarEvent"
+ *         {
+ *           authToken: auth.authToken,
+ *           calendarId: primaryCalendar.id
+ *         },
+ *         this.onCalendarEvent,
+ *         { initialSync: true }
  *       );
  *     }
  *   }
@@ -151,27 +155,24 @@ export interface CalendarTool {
    * - Use Uuid.Generate() and store ID mappings when creating multiple activities per event
    * - See SYNC_STRATEGIES.md for when this is appropriate
    *
-   * @param authToken - Authorization token for calendar access
-   * @param calendarId - ID of the calendar to sync
+   * @param options - Sync configuration options
+   * @param options.authToken - Authorization token for calendar access
+   * @param options.calendarId - ID of the calendar to sync
+   * @param options.timeMin - Earliest date to sync events from (inclusive)
+   * @param options.timeMax - Latest date to sync events to (exclusive)
    * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced event
-   * @param extraArgs - Additional arguments to pass to the callback (type-checked)
+   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    * @throws When auth token is invalid or calendar doesn't exist
    */
-  startSync<
-    TCallback extends (
-      syncUpdate: SyncUpdate,
-      ...args: any[]
-    ) => any
-  >(
-    authToken: string,
-    calendarId: string,
+  startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(
+    options: {
+      authToken: string;
+      calendarId: string;
+    } & SyncOptions,
     callback: TCallback,
-    ...extraArgs: TCallback extends (
-      syncUpdate: any,
-      ...rest: infer R
-    ) => any
-      ? R
+    ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any
+      ? NoFunctions<R>
       : []
   ): Promise<void>;
 

twister/src/common/messaging.ts

@@ -1,4 +1,5 @@
 import type { ActivityLink, NewActivityWithNotes, SyncUpdate } from "../index";
+import type { NoFunctions } from "../utils/types";
 
 /**
  * Represents a successful messaging service authorization.
@@ -91,22 +92,22 @@ export interface MessagingTool {
    * - Use Uuid.Generate() and store ID mappings when creating multiple activities per thread
    * - See SYNC_STRATEGIES.md for when this is appropriate
    *
-   * @param authToken - Authorization token for access
-   * @param channelId - ID of the channel (e.g., channel, inbox) to sync
+   * @param options - Sync configuration options
+   * @param options.authToken - Authorization token for access
+   * @param options.channelId - ID of the channel (e.g., channel, inbox) to sync
+   * @param options.timeMin - Earliest date to sync events from (inclusive)
    * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced conversation
-   * @param options - Optional configuration for limiting the sync scope (e.g., time range)
-   * @param extraArgs - Additional arguments to pass to the callback (type-checked)
+   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    */
-  startSync<
-    TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any
-  >(
-    authToken: string,
-    channelId: string,
+  startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(
+    options: {
+      authToken: string;
+      channelId: string;
+    } & MessageSyncOptions,
     callback: TCallback,
-    options?: MessageSyncOptions,
     ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any
-      ? R
+      ? NoFunctions<R>
       : []
   ): Promise<void>;
 

twister/src/common/projects.ts

@@ -4,6 +4,7 @@ import type {
   NewActivityWithNotes,
   SyncUpdate,
 } from "../index";
+import type { NoFunctions } from "../utils/types";
 
 /**
  * Represents a successful project management service authorization.
@@ -98,28 +99,22 @@ export interface ProjectTool {
    * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue
    * - See SYNC_STRATEGIES.md for when this is appropriate
    *
-   * @param authToken - Authorization token for access
-   * @param projectId - ID of the project to sync
+   * @param options - Sync configuration options
+   * @param options.authToken - Authorization token for access
+   * @param options.projectId - ID of the project to sync
+   * @param options.timeMin - Earliest date to sync issues from (inclusive)
    * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced issue
-   * @param options - Optional configuration for limiting the sync scope (e.g., time range)
-   * @param extraArgs - Additional arguments to pass to the callback (type-checked)
+   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    */
-  startSync<
-    TCallback extends (
-      syncUpdate: SyncUpdate,
-      ...args: any[]
-    ) => any
-  >(
-    authToken: string,
-    projectId: string,
+  startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(
+    options: {
+      authToken: string;
+      projectId: string;
+    } & ProjectSyncOptions,
     callback: TCallback,
-    options?: ProjectSyncOptions,
-    ...extraArgs: TCallback extends (
-      syncUpdate: any,
-      ...rest: infer R
-    ) => any
-      ? R
+    ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any
+      ? NoFunctions<R>
       : []
   ): Promise<void>;
 

twister/src/plot.ts

@@ -1,9 +1,71 @@
 import { type Tag } from "./tag";
 import { type Callback } from "./tools/callbacks";
+import { type JSONValue } from "./utils/types";
 import { Uuid } from "./utils/uuid";
 
 export { Tag } from "./tag";
 export { Uuid } from "./utils/uuid";
+export { type JSONValue } from "./utils/types";
+
+/**
+ * @fileoverview
+ * Core Plot entity types for working with activities, notes, priorities, and contacts.
+ *
+ * ## Type Pattern: Null vs Undefined Semantics
+ *
+ * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:
+ *
+ * ### Entity Types (Activity, Priority, Note, Actor)
+ * - **Required fields**: No `?`, cannot be `undefined`
+ *   - Example: `id: Uuid`, `type: ActivityType`
+ * - **Nullable fields**: Use `| null` to allow explicit clearing
+ *   - Example: `assignee: ActorId | null`, `done: Date | null`
+ *   - `null` = field is explicitly unset/cleared
+ *   - Non-null value = field has a value
+ * - **Optional nullable fields**: Use `?` with `| null` for permission-based access
+ *   - Example: `email?: string | null`, `name?: string | null`
+ *   - `undefined` = field not included (e.g., no permission to access)
+ *   - `null` = field included but not set
+ *   - Value = field has a value
+ *
+ * ### New* Types (NewActivity, NewNote, NewPriority)
+ * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:
+ * - **Required fields**: Must be provided (no `?`)
+ *   - Example: `type: ActivityType` in NewActivity
+ * - **Optional fields**: Use `?` to make them optional
+ *   - Example: `title?: string`, `author?: NewActor`
+ *   - `undefined` (omitted) = don't set/update this field
+ *   - Provided value = set/update this field
+ * - **Optional nullable fields**: Use `?` with `| null` to support clearing
+ *   - Example: `assignee?: NewActor | null`
+ *   - `undefined` (omitted) = don't change assignee
+ *   - `null` = clear the assignee
+ *   - NewActor = set/update the assignee
+ *
+ * This pattern allows API consumers to:
+ * 1. Omit fields they don't want to change (undefined)
+ * 2. Explicitly clear fields by setting to null
+ * 3. Set or update fields by providing values
+ *
+ * @example
+ * ```typescript
+ * // Creating a new activity
+ * const newActivity: NewActivity = {
+ *   type: ActivityType.Action,  // Required
+ *   title: "Review PR",          // Optional, provided
+ *   assignee: null,              // Optional nullable, explicitly clearing
+ *   // priority is omitted (undefined), will auto-select or use default
+ * };
+ *
+ * // Updating an activity - only change what's specified
+ * const update: ActivityUpdate = {
+ *   id: activityId,
+ *   done: new Date(),       // Mark as done
+ *   assignee: null,         // Clear assignee
+ *   // title is omitted, won't be changed
+ * };
+ * ```
+ */
 
 /**
  * Represents a unique user, contact, or twist in Plot.
@@ -24,21 +86,55 @@ export type ActorId = string & { readonly __brand: "ActorId" };
  */
 export type Priority = {
   /** Unique identifier for the priority */
-  id: string;
+  id: Uuid;
   /** Human-readable title for the priority */
   title: string;
+  /** Whether this priority has been archived */
+  archived: boolean;
 };
 
 /**
  * Type for creating new priorities.
  *
- * Excludes the auto-generated ID field and adds an optional parentId
- * for creating hierarchical priority structures.
+ * Supports multiple creation patterns:
+ * - Provide a specific UUID for the priority
+ * - Provide a key for upsert within the user's priorities
+ * - Omit both to auto-generate a new UUID
+ *
+ * Optionally specify a parent priority by ID or key for hierarchical structures.
  */
-export type NewPriority = Omit<Priority, "id"> & {
-  /** Optional ID of the parent priority for creating hierarchies */
-  parentId?: string;
-};
+export type NewPriority = Pick<Priority, "title"> &
+  Partial<Omit<Priority, "id" | "title">> &
+  (
+    | {
+        /**
+         * Unique identifier for the priority, generated by Uuid.Generate().
+         * Specifying an ID allows tools to track and upsert priorities.
+         */
+        id: Uuid;
+      }
+    | {
+        /**
+         * Unique key for the priority within the user's priorities.
+         * Can be used to upsert without knowing the UUID.
+         * For example, "@plot" identifies the Plot priority.
+         */
+        key: string;
+      }
+    | {
+        /* Neither id nor key is required. An id will be generated and returned. */
+      }
+  ) & {
+    /** Add the new priority as the child of another priority */
+    parent?: { id: Uuid } | { key: string };
+  };
+
+/**
+ * Type for updating existing priorities.
+ * Must provide either id or key to identify the priority to update.
+ */
+export type PriorityUpdate = ({ id: Uuid } | { key: string }) &
+  Partial<Pick<Priority, "title" | "archived">>;
 
 /**
  * Enumeration of supported activity types in Plot.
@@ -178,6 +274,9 @@ export type ActivityLink =
  * which is useful for synchronization, linking back to external systems,
  * and storing tool-specific data.
  *
+ * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).
+ * Functions and other non-JSON values are not supported.
+ *
  * @example
  * ```typescript
  * // Calendar event metadata
@@ -206,7 +305,7 @@ export type ActivityLink =
  */
 export type ActivityMeta = {
   /** Source-specific properties and metadata */
-  [key: string]: any;
+  [key: string]: JSONValue;
 };
 
 /**
@@ -414,8 +513,8 @@ export type NewActivityWithNotes = NewActivity & {
  * // Score based on content (max 100 points) and require exact type match
  * pickPriority: { content: 100, type: true }
  *
- * // Match on meta source and score content
- * pickPriority: { "meta.source": true, content: 50 }
+ * // Match on meta and score content
+ * pickPriority: { "meta.projectId": true, content: 50 }
  * ```
  */
 export type PickPriorityConfig = {
@@ -590,6 +689,7 @@ export type ActivityUpdate = (
       | "assignee"
       | "draft"
       | "private"
+      | "archived"
       | "meta"
       | "recurrenceRule"
       | "recurrenceDates"
@@ -732,7 +832,9 @@ export type NewNote = Partial<
  * Must provide either id or key to identify the note to update.
  */
 export type NoteUpdate = ({ id: Uuid } | { key: string }) &
-  Partial<Pick<Note, "draft" | "private" | "content" | "links">> & {
+  Partial<
+    Pick<Note, "draft" | "private" | "archived" | "content" | "links">
+  > & {
     /**
      * Format of the note content. Determines how the note is processed:
      * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)
@@ -781,9 +883,19 @@ export type Actor = {
   id: ActorId;
   /** Type of actor (User, Contact, or Twist) */
   type: ActorType;
-  /** Email address (only included with ContactAccess.Read permission) */
-  email?: string;
-  /** Display name (undefined if not included due to permissions, null if not set) */
+  /**
+   * Email address (only included with ContactAccess.Read permission).
+   * - `undefined`: No permission to read email
+   * - `null`: Permission granted but email not set
+   * - `string`: Email address
+   */
+  email?: string | null;
+  /**
+   * Display name.
+   * - `undefined`: Not included due to permissions
+   * - `null`: Not set
+   * - `string`: Display name
+   */
   name?: string | null;
 };