@plotday/twister 0.47.0 → 0.49.0

package/src/tools/integrations.ts

@@ -0,0 +1,352 @@
+import {
+  type Actor,
+  type ActorId,
+  type NewContact,
+  type NewLinkWithNotes,
+  ITool,
+  Serializable,
+} from "..";
+import { Tag } from "../tag";
+import type { JSONValue } from "../utils/types";
+import type { Uuid } from "../utils/uuid";
+
+/**
+ * A resource that can be synced (e.g., a calendar, project, channel).
+ * Returned by getChannels() and managed by users in the twist setup/edit modal.
+ */
+export type Channel = {
+  /** External ID shared across users (e.g., Google calendar ID) */
+  id: string;
+  /** Display name shown in the UI */
+  title: string;
+  /** Optional nested channel resources (e.g., subfolders) */
+  children?: Channel[];
+  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */
+  linkTypes?: LinkTypeConfig[];
+};
+
+/**
+ * Describes a link type that a connector creates.
+ * Used for display in the UI (icons, labels).
+ */
+export type LinkTypeConfig = {
+  /** Machine-readable type identifier (e.g., "issue", "pull_request") */
+  type: string;
+  /** Human-readable label (e.g., "Issue", "Pull Request") */
+  label: string;
+  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */
+  logo?: string;
+  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */
+  logoDark?: string;
+  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */
+  logoMono?: string;
+  /** Possible status values for this type */
+  statuses?: Array<{
+    /** Machine-readable status (e.g., "open", "done") */
+    status: string;
+    /** Human-readable label (e.g., "Open", "Done") */
+    label: string;
+    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */
+    tag?: Tag;
+    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */
+    done?: boolean;
+    /**
+     * Whether this status represents the connector's "to-do" / active state.
+     * When a user adds a thread to Plot's agenda, done-status links flip to
+     * the status marked `todo: true` (e.g., Gmail's "starred", Linear's
+     * "todo") so the link widget and thread tags reflect the active state.
+     * At most one status per type should set this.
+     */
+    todo?: boolean;
+    /**
+     * Default status applied when Plot asks the connector to create a new
+     * item of this type via `Connector.onCreateLink`. Declaring at least one
+     * status with `createDefault: true` is how a link type opts in to
+     * Plot-initiated creation. At most one status per type should set this.
+     */
+    createDefault?: boolean;
+  }>;
+  /** Whether this link type supports displaying and changing the assignee */
+  supportsAssignee?: boolean;
+  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */
+  defaultCreateThreads?: string;
+};
+
+/**
+ * Context passed to onChannelEnabled with plan-based sync hints.
+ * Connectors can use these hints to limit initial sync scope.
+ */
+export type SyncContext = {
+  /**
+   * Earliest date to include in initial sync, based on the user's plan.
+   *
+   * Non-calendar connectors should use this as their date filter (timeMin,
+   * created.gte, etc.) during initial sync. Calendar connectors should
+   * ignore this for API queries (to avoid missing recurring events) — the
+   * API layer filters non-recurring items automatically.
+   *
+   * Undefined when no limit applies.
+   */
+  syncHistoryMin?: Date;
+};
+
+/**
+ * Built-in tool for managing OAuth authentication and channel resources.
+ *
+ * The Integrations tool:
+ * 1. Manages channel resources (calendars, projects, etc.) per actor
+ * 2. Returns tokens for the user who enabled sync on a channel
+ * 3. Supports per-actor auth via actAs() for write-back operations
+ * 4. Provides saveLink/saveContacts for Connectors to save data directly
+ *
+ * Connectors declare their provider, scopes, and channel lifecycle methods as
+ * class properties and methods. The Integrations tool reads these automatically.
+ * Auth and channel management is handled in the twist edit modal in Flutter.
+ *
+ * @example
+ * ```typescript
+ * class CalendarConnector extends Connector<CalendarConnector> {
+ *   readonly provider = AuthProvider.Google;
+ *   readonly scopes = ["https://www.googleapis.com/auth/calendar"];
+ *
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       integrations: build(Integrations),
+ *     };
+ *   }
+ *
+ *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {
+ *     const calendars = await this.listCalendars(token);
+ *     return calendars.map(c => ({ id: c.id, title: c.name }));
+ *   }
+ *
+ *   async onChannelEnabled(channel: Channel) {
+ *     // Start syncing
+ *   }
+ *
+ *   async onChannelDisabled(channel: Channel) {
+ *     // Stop syncing
+ *   }
+ * }
+ * ```
+ */
+export abstract class Integrations extends ITool {
+  /**
+   * Merge scopes from multiple tools, deduplicating.
+   *
+   * @param scopeArrays - Arrays of scopes to merge
+   * @returns Deduplicated array of scopes
+   */
+  static MergeScopes(...scopeArrays: string[][]): string[] {
+    return Array.from(new Set(scopeArrays.flat()));
+  }
+
+  /**
+   * Retrieves an access token for a channel resource.
+   *
+   * Returns the token of the user who enabled sync on the given channel.
+   * If the channel is not enabled or the token is expired/invalid, returns null.
+   *
+   * @param channelId - The channel resource ID (e.g., calendar ID)
+   * @returns Promise resolving to the access token or null
+   */
+  abstract get(channelId: string): Promise<AuthToken | null>;
+  /**
+   * Retrieves an access token for a channel resource.
+   *
+   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)
+   * @param channelId - The channel resource ID (e.g., calendar ID)
+   * @returns Promise resolving to the access token or null
+   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;
+
+  /**
+   * Execute a callback as a specific actor, requesting auth if needed.
+   *
+   * If the actor has a valid token, calls the callback immediately with it.
+   * If the actor has no token, creates a private auth note in the specified
+   * activity prompting them to connect. Once they authorize, this callback fires.
+   *
+   * @param provider - The OAuth provider
+   * @param actorId - The actor to act as
+   * @param activityId - The activity to create an auth note in (if needed)
+   * @param callback - Function to call with the token
+   * @param extraArgs - Additional arguments to pass to the callback
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract actAs<
+    TArgs extends Serializable[],
+    TCallback extends (token: AuthToken, ...args: TArgs) => any
+  >(
+    provider: AuthProvider,
+    actorId: ActorId,
+    activityId: Uuid,
+    callback: TCallback,
+    ...extraArgs: TArgs
+  ): Promise<void>;
+
+  /**
+   * Saves a link with notes to the connector's priority.
+   *
+   * Creates a thread+link pair. The thread is a lightweight container;
+   * the link holds the external entity data (source, meta, type, status, etc.).
+   *
+   * This method is available only to Connectors (not regular Twists).
+   *
+   * @param link - The link with notes to save
+   * @returns Promise resolving to the saved thread's UUID, or null if the
+   *   link was filtered out (e.g. older than the plan's sync history limit)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;
+
+  /**
+   * Batch version of {@link saveLink} — saves many links in one call.
+   *
+   * Connectors syncing many items per page (e.g. calendar events, issues,
+   * messages) should prefer this over looping `saveLink`. Each `saveLink`
+   * crosses the runtime boundary and counts against the per-execution
+   * request budget; `saveLinks` collapses N saves into a single crossing.
+   *
+   * Failures on individual links DO NOT abort the batch. A bad item lands
+   * as `null` in its slot and the rest still save. This prevents one
+   * malformed record from losing an entire page of sync progress.
+   *
+   * This method is available only to Connectors (not regular Twists).
+   *
+   * @param links - Array of links with notes to save
+   * @returns Array of the same length and order as `links`. Each entry is
+   *   the saved thread's UUID, or `null` if the link was filtered out
+   *   (e.g. older than the plan's sync history limit) OR failed to save.
+   *   The two null causes are not distinguished; the save failure is
+   *   logged server-side.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;
+
+  /**
+   * Saves contacts to the connector's priority.
+   *
+   * @param contacts - Array of contacts to save
+   * @returns Promise resolving to the saved actors
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;
+
+  /**
+   * Archives links matching the given filter that were created by this connector.
+   *
+   * For each archived link's thread, if no other non-archived links remain,
+   * the thread is also archived.
+   *
+   * @param filter - Filter criteria for which links to archive
+   * @returns Promise that resolves when archiving is complete
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;
+
+  /**
+   * Sets or clears todo status on a thread owned by this connector.
+   *
+   * @param source - The link source URL identifying the thread
+   * @param actorId - The user to set the todo for
+   * @param todo - true to mark as todo, false to clear/complete
+   * @param options - Additional options
+   * @param options.date - The todo date (when todo=true). Defaults to today.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract setThreadToDo(
+    source: string,
+    actorId: ActorId,
+    todo: boolean,
+    options?: { date?: Date | string }
+  ): Promise<void>;
+
+}
+
+/**
+ * Filter criteria for archiving links.
+ * All fields are optional; only provided fields are used for matching.
+ */
+export type ArchiveLinkFilter = {
+  /** Filter by channel ID */
+  channelId?: string;
+  /** Filter by link type (e.g., "issue", "pull_request") */
+  type?: string;
+  /** Filter by link status (e.g., "open", "closed") */
+  status?: string;
+  /** Filter by metadata fields (uses containment matching) */
+  meta?: Record<string, JSONValue>;
+};
+
+/**
+ * Enumeration of supported OAuth providers.
+ *
+ * Each provider has different OAuth endpoints, scopes, and token formats.
+ * The Integrations tool handles the provider-specific implementation details.
+ */
+export enum AuthProvider {
+  /** Google OAuth provider for Google Workspace services */
+  Google = "google",
+  /** Microsoft OAuth provider for Microsoft 365 services */
+  Microsoft = "microsoft",
+  /** Notion OAuth provider for Notion workspaces */
+  Notion = "notion",
+  /** Slack OAuth provider for Slack workspaces */
+  Slack = "slack",
+  /** Atlassian OAuth provider for Jira and Confluence */
+  Atlassian = "atlassian",
+  /** Linear OAuth provider for Linear workspaces */
+  Linear = "linear",
+  /** Monday.com OAuth provider */
+  Monday = "monday",
+  /** GitHub OAuth provider for GitHub repositories and organizations */
+  GitHub = "github",
+  /** Asana OAuth provider for Asana workspaces */
+  Asana = "asana",
+  /** HubSpot OAuth provider for HubSpot CRM */
+  HubSpot = "hubspot",
+  /** Todoist OAuth provider for Todoist task management */
+  Todoist = "todoist",
+  /** Airtable OAuth provider for Airtable bases */
+  Airtable = "airtable",
+}
+
+/**
+ * Represents a completed authorization from an OAuth flow.
+ *
+ * Contains the provider, granted scopes, and the actor (contact) that was authorized.
+ * Tokens are looked up by (provider, actorId) rather than a random ID.
+ */
+export type Authorization = {
+  /** The OAuth provider this authorization is for */
+  provider: AuthProvider;
+  /** Array of OAuth scopes this authorization covers */
+  scopes: string[];
+  /** The external account that was authorized (e.g., the Google account) */
+  actor: Actor;
+};
+
+/**
+ * Represents a stored OAuth authentication token.
+ *
+ * Contains the actual access token and the scopes it was granted,
+ * which may be a subset of the originally requested scopes.
+ */
+export type AuthToken = {
+  /** The OAuth access token */
+  token: string;
+  /** Array of granted OAuth scopes */
+  scopes: string[];
+  /**
+   * Provider-specific metadata as key-value pairs.
+   *
+   * For Slack (AuthProvider.Slack):
+   * - authed_user_id: The authenticated user's Slack ID
+   * - bot_user_id: The bot user's Slack ID
+   * - team_name: The Slack workspace/team name
+   */
+  provider?: Record<string, string>;
+};

package/src/tools/network.ts

@@ -0,0 +1,240 @@
+import { ITool } from "..";
+import { type JSONValue, Serializable } from "../utils/types";
+import { type AuthProvider, type Authorization } from "./integrations";
+
+/**
+ * Represents an incoming webhook request.
+ *
+ * This object is passed to webhook callback functions and contains all
+ * the information about the HTTP request that triggered the webhook.
+ *
+ * @example
+ * ```typescript
+ * async onWebhookReceived(request: WebhookRequest, context: any) {
+ *   console.log(`${request.method} request received`);
+ *   console.log("Headers:", request.headers);
+ *   console.log("Query params:", request.params);
+ *   console.log("Body:", request.body);
+ *   console.log("Context:", context);
+ * }
+ * ```
+ */
+export type WebhookRequest = {
+  /** HTTP method of the request (GET, POST, etc.) */
+  method: string;
+  /** HTTP headers from the request */
+  headers: Record<string, string>;
+  /** Query string parameters from the request URL */
+  params: Record<string, string>;
+  /** Request body (parsed as JSON if applicable) */
+  body: JSONValue;
+  /** Raw request body (for signature verification) */
+  rawBody?: string;
+};
+
+/**
+ * Built-in tool for requesting HTTP access permissions and managing webhooks.
+ *
+ * The Network tool serves two purposes:
+ * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS
+ * 2. Provides webhook creation and management for receiving HTTP callbacks
+ *
+ * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare
+ * HTTP access permissions. Without requesting this tool with the appropriate URLs,
+ * all outbound HTTP requests (fetch, etc.) will be blocked.
+ *
+ * **Permission Patterns:**
+ * - `*` - Allow access to all URLs
+ * - `https://*.example.com` - Allow access to all subdomains
+ * - `https://api.example.com/*` - Allow access to all paths on the domain
+ * - `https://api.example.com/v1/*` - Allow access to specific path prefix
+ *
+ * **Webhook Characteristics:**
+ * - Persistent across worker restarts
+ * - Automatic callback routing to parent tool/twist
+ * - Support for all HTTP methods
+ * - Context preservation for callback execution
+ *
+ * @example
+ * ```typescript
+ * class MyTwist extends Twist<MyTwist> {
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       // Request HTTP access to specific APIs
+ *       network: build(Network, {
+ *         urls: [
+ *           'https://api.github.com/*',
+ *           'https://api.openai.com/*'
+ *         ]
+ *       })
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class CalendarTool extends Tool<CalendarTool> {
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       network: build(Network, {
+ *         urls: ['https://www.googleapis.com/calendar/*']
+ *       })
+ *     };
+ *   }
+ *
+ *   async setupCalendarWebhook(calendarId: string) {
+ *     // Create webhook URL that will call onCalendarEvent
+ *     const webhookUrl = await this.tools.network.createWebhook(
+ *       {},
+ *       this.onCalendarEvent,
+ *       calendarId,
+ *       "google"
+ *     );
+ *
+ *     // Register webhook with Google Calendar API
+ *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);
+ *
+ *     return webhookUrl;
+ *   }
+ *
+ *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {
+ *     console.log("Calendar event received:", {
+ *       method: request.method,
+ *       calendarId,
+ *       provider,
+ *       body: request.body
+ *     });
+ *
+ *     // Process the calendar event change
+ *     await this.processCalendarChange(request.body);
+ *   }
+ *
+ *   async cleanup(webhookUrl: string) {
+ *     await this.tools.network.deleteWebhook(webhookUrl);
+ *   }
+ * }
+ * ```
+ */
+export abstract class Network extends ITool {
+  static readonly Options: {
+    /**
+     * All network access is blocked except the specified URLs.
+     * Wildcards (*) are supported for domains and paths.
+     */
+    urls: string[];
+  };
+
+  /**
+   * Creates a new webhook endpoint.
+   *
+   * Generates a unique HTTP endpoint that will invoke the callback function
+   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.
+   *
+   * **Provider-Specific Behavior:**
+   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.
+   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.
+   *   The topic name (e.g., "projects/plot-prod/topics/gmail-webhook-abc123") should be passed
+   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.
+   * - **Pub/Sub** (`pubsub: true`): Returns a Google Pub/Sub topic name instead of a webhook URL.
+   *   Use this for services that deliver events via Pub/Sub (e.g., Google Workspace Events API).
+   *   A Pub/Sub topic and push subscription are created automatically; the returned topic name
+   *   can be passed to any Google API that accepts a Pub/Sub notification endpoint.
+   * - **Default**: Returns a standard webhook URL for all other cases.
+   *
+   * @param options - Webhook creation options
+   * @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/Pub/Sub, a Pub/Sub topic name
+   *
+   * @example
+   * ```typescript
+   * // Pub/Sub webhook for Workspace Events API
+   * const topicName = await this.tools.network.createWebhook(
+   *   { pubsub: true },
+   *   this.onEventReceived,
+   *   channelId
+   * );
+   * // topicName: "projects/plot-prod/topics/ps-abc123"
+   *
+   * // Pass topic name to Workspace Events API
+   * await api.createSubscription(targetResource, topicName, eventTypes);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Gmail webhook - auto-detected from scopes, returns Pub/Sub topic name
+   * const topicName = await this.tools.network.createWebhook(
+   *   {},
+   *   this.onGmailNotification,
+   *   "inbox"
+   * );
+   * ```
+   */
+  abstract createWebhook<
+    TArgs extends Serializable[],
+    TCallback extends (request: WebhookRequest, ...args: TArgs) => any
+  >(
+    options: {
+      provider?: AuthProvider;
+      authorization?: Authorization;
+      /** When true, creates a Google Pub/Sub topic instead of a webhook URL. */
+      pubsub?: boolean;
+      /**
+       * Controls whether the returned webhook URL runs callbacks synchronously
+       * or asynchronously.
+       *
+       * **Async (default, `async: true`)** — Plot enqueues each incoming
+       * request and immediately returns `200 { queued: true }`. A background
+       * queue consumer runs the callback with bounded concurrency. The
+       * sender never sees the callback's return value or any error thrown
+       * by it, and delivery is at-least-once (the callback must be
+       * idempotent). This is the right default for the vast majority of
+       * webhooks — service event notifications, bulk-import fan-out, etc. —
+       * because it removes ingress-path database pressure and prevents
+       * sender-side retry storms when callbacks are slow.
+       *
+       * **Sync (`async: false`)** — Plot runs the callback inline and
+       * responds with the callback's return value. Required when:
+       * - The sender reads the response body (e.g. Microsoft Graph
+       *   subscription validation, which POSTs with a `validationToken` and
+       *   expects the token echoed as `text/plain`).
+       * - The sender uses the HTTP status code to decide whether to retry
+       *   (e.g. to surface 4xx for permanent failures).
+       * - The handler must observe throws before the sender times out.
+       *
+       * When `async: false`, a callback returning a `string` is sent back
+       * with `Content-Type: text/plain`; any other value is serialized as
+       * JSON. `undefined` / `void` yields a plain `200 OK` body.
+       *
+       * Defaults to `true`.
+       */
+      async?: boolean;
+    },
+    callback: TCallback,
+    ...extraArgs: TArgs
+  ): Promise<string>;
+
+  /**
+   * Deletes an existing webhook endpoint.
+   *
+   * Removes the webhook endpoint and stops processing requests.
+   * Works with all webhook types (standard, Slack, and Gmail).
+   *
+   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.
+   *
+   * **For Slack webhooks:** Removes the callback registration for the specific team.
+   *
+   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests
+   * to the deleted webhook will return 404.
+   *
+   * @param url - The webhook identifier returned from `createWebhook()`.
+   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),
+   *              or an opaque identifier (Slack). Always pass the exact value returned
+   *              from `createWebhook()`.
+   * @returns Promise that resolves when the webhook is deleted
+   */
+  abstract deleteWebhook(url: string): Promise<void>;
+}