@plotday/twister 0.49.0 → 0.51.0

package/src/tools/integrations.ts

@@ -88,6 +88,29 @@ export type SyncContext = {
    * Undefined when no limit applies.
    */
   syncHistoryMin?: Date;
+
+  /**
+   * True when this is a recovery dispatch after the connection's auth was
+   * restored (the user re-authorized a previously-broken connection).
+   *
+   * The framework calls `onChannelEnabled` again for every channel that was
+   * already enabled at the time of re-auth so the connector can recover from
+   * the auth gap. Connectors should:
+   *
+   * 1. Drop any persisted incremental sync cursors / sync tokens so the
+   *    next sync re-walks history (the cursor may be stale or invalid —
+   *    Google Calendar invalidates syncTokens after ~7 days).
+   * 2. Re-register webhooks (any prior subscription may have been
+   *    invalidated during the auth outage).
+   * 3. Treat this as a backfill that walks history but does NOT spam
+   *    notifications — set `unread: false` and `archived: false` on
+   *    items as you would during initial sync.
+   *
+   * Most connectors can take the same code path as a fresh
+   * `onChannelEnabled` for `recovering: true` as long as that path
+   * overwrites stored state rather than appending to it.
+   */
+  recovering?: boolean;
 };
 
 /**
@@ -264,6 +287,52 @@ export abstract class Integrations extends ITool {
     options?: { date?: Date | string }
   ): Promise<void>;
 
+  /**
+   * Signal that initial bulk-sync (or recovery sync) for a channel is fully
+   * complete. The Flutter app uses this to clear the "syncing…" indicator
+   * on the connection.
+   *
+   * The framework automatically marks a channel as syncing when it dispatches
+   * `onChannelEnabled` (whether initial-enable, auto-enable from
+   * `setChannels`, or recovery after re-auth). Connectors do NOT need to
+   * call anything to start tracking — only to signal completion.
+   *
+   * Call this exactly once when the initial backfill has finished (no more
+   * pages, all phases exhausted). Do NOT call it on every incremental sync.
+   *
+   * If `onChannelEnabled` throws an unhandled exception, the framework
+   * automatically clears the syncing state — connectors don't need a
+   * `try/catch` to clear state on failure.
+   *
+   * No-op when no auth/user mapping exists for the channel (e.g. key-based
+   * connectors that don't have a per-user OAuth association).
+   *
+   * @param channelId - The channel resource ID whose initial sync just finished
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract channelSyncCompleted(channelId: string): Promise<void>;
+
+  /**
+   * Flag a connection as needing re-authentication so the Flutter app
+   * surfaces a re-auth prompt on the next sync.
+   *
+   * Call this when a connector's API call returns a permanent auth-style
+   * error that the runtime can't observe through token refresh — e.g.
+   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a
+   * provider that doesn't refresh. The runtime already flags reauth
+   * automatically when an OAuth refresh permanently fails or when the
+   * stored token is missing on a get(); only call this for cases the
+   * runtime can't see.
+   *
+   * Idempotent: safe to call repeatedly; existing reauth flags are not
+   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.
+   * key-based connectors).
+   *
+   * @param channelId - The channel resource ID whose token is bad
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract markNeedsReauth(channelId: string): Promise<void>;
+
 }
 
 /**

package/src/tools/plot.ts

@@ -542,18 +542,6 @@ export abstract class Plot extends ITool {
    */
   abstract getUserId(): Promise<string>;
 
-  /**
-   * Returns the owner user's root priority ID. Used as the implicit default
-   * when an operation needs a priority but the caller didn't supply one —
-   * for example, `plot.createPriority()` without a parent, or
-   * `plot.getThreads()` without an explicit `priorityId`.
-   *
-   * On the server, priority resolution for newly created threads/links
-   * happens automatically via `match_priority_for_user`; twists rarely need
-   * to call this directly.
-   */
-  abstract getDefaultPriorityId(): Promise<string>;
-
   /**
    * Creates a new schedule for a thread.
    *

package/src/tools/store.ts

@@ -146,4 +146,48 @@ export abstract class Store extends ITool {
    * @returns Promise that resolves when all keys are removed
    */
   abstract clearAll(): Promise<void>;
+
+  /**
+   * Acquire a self-expiring lock. Returns true if the caller now holds the
+   * lock, false if another holder has a non-expired lease.
+   *
+   * Use this for any operation where you previously hand-rolled a boolean
+   * "in progress" flag with manual cleanup on every error path. The lock
+   * auto-releases after `ttlMs`, so a crashed/timed-out holder cannot wedge
+   * the system permanently — pick a `ttlMs` comfortably longer than the
+   * worst-case duration of the protected work.
+   *
+   * Acquisition is atomic across concurrent callers (the underlying
+   * Durable Object serializes operations). Lock keys live in a reserved
+   * namespace and never appear in `get` / `list` results.
+   *
+   * @example
+   * ```typescript
+   * if (!(await this.tools.store.acquireLock(`sync_${id}`, 30 * 60_000))) {
+   *   return; // another sync is already running
+   * }
+   * try {
+   *   await this.runSync(id);
+   * } finally {
+   *   await this.tools.store.releaseLock(`sync_${id}`);
+   * }
+   * ```
+   *
+   * @param key Lock identifier (any string).
+   * @param ttlMs Lease duration in milliseconds. After this time the lock
+   *   is considered expired and a new caller can acquire it even if
+   *   `releaseLock` was never called.
+   * @returns Promise resolving to true if acquired, false if held.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract acquireLock(key: string, ttlMs: number): Promise<boolean>;
+
+  /**
+   * Release a lock acquired via {@link acquireLock}. Safe to call even if
+   * the caller never acquired the lock or the lease has already expired.
+   *
+   * @param key The same key that was passed to `acquireLock`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract releaseLock(key: string): Promise<void>;
 }