@kubun/plugin-connector 0.14.0 → 0.14.2

package/lib/manager.js

@@ -3,12 +3,22 @@ export class ConnectorManager {
     #registry;
     #logger;
     #activeGraphs = new Map();
-    #events = new EventEmitter();
-    #syncEvents = new EventEmitter();
+    #events;
+    #syncEvents;
+    #lifecycleEvents;
     #defaults;
     constructor(params){
         this.#registry = params.registry;
         this.#logger = params.logger;
+        this.#events = new EventEmitter({
+            logger: params.logger
+        });
+        this.#syncEvents = new EventEmitter({
+            logger: params.logger
+        });
+        this.#lifecycleEvents = new EventEmitter({
+            logger: params.logger
+        });
         this.#defaults = {
             boundary: params.defaults?.boundary ?? {
                 maxAge: 'P90D'
@@ -35,7 +45,7 @@ export class ConnectorManager {
                     name,
                     graphID
                 });
-                this.#events.emit('connector:activated', {
+                this.#events.fire('connector:activated', {
                     connectorName: name,
                     graphID
                 });
@@ -54,7 +64,7 @@ export class ConnectorManager {
                 this.#logger.info('Connector {name} deactivated', {
                     name
                 });
-                this.#events.emit('connector:deactivated', {
+                this.#events.fire('connector:deactivated', {
                     connectorName: name
                 });
             }
@@ -77,11 +87,36 @@ export class ConnectorManager {
     onConnectorDeactivated(callback) {
         return this.#events.on('connector:deactivated', callback);
     }
+    /**
+   * Listen-only view of the typed event channel. Consumers subscribe here (e.g.
+   * `events.on('connector:authenticated', …)`); the emit side stays private to
+   * the manager, so the returned surface carries no `fire`/`emit`.
+   */ get events() {
+        return this.#events;
+    }
+    /** Listen-only view of the merged lifecycle channel carrying every tagged event. */ get lifecycleEvents() {
+        return this.#lifecycleEvents;
+    }
+    /**
+   * Emit a lifecycle event to both the typed per-event channel and the merged
+   * channel. The two `fire` calls are independent and failure-isolated: a
+   * throwing listener on either channel is reported via the logger and cannot
+   * reject the caller or block the other channel.
+   */ emitLifecycle(type, payload) {
+        this.#emitLifecycle(type, payload);
+    }
+    #emitLifecycle(type, payload) {
+        this.#events.fire(type, payload);
+        this.#lifecycleEvents.fire('lifecycle', {
+            type,
+            ...payload
+        });
+    }
     get syncEvents() {
         return this.#syncEvents;
     }
-    async emitSyncEvent(event) {
-        await this.#syncEvents.emit('sync', event);
+    emitSyncEvent(event) {
+        this.#syncEvents.fire('sync', event);
     }
     onSyncEvent(callback) {
         return this.#syncEvents.on('sync', callback);

package/lib/oauth.d.ts

@@ -4,6 +4,10 @@ import type { Runtime } from '@sozai/runtime';
 import type { ConnectorAPI, CredentialAPI } from './api.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, StartConnectorAuthInput, StartConnectorAuthOutput } from './schema.js';
+export type CompleteAuthResult = {
+    output: CompleteConnectorAuthOutput;
+    ownerDID: string;
+};
 export type OAuthServiceParams = {
     runtime: Runtime;
     providers: Array<OAuthProviderDefinition>;
@@ -16,5 +20,5 @@ export declare class OAuthService {
     #private;
     constructor(params: OAuthServiceParams);
     startAuth(args: StartConnectorAuthInput, ownerDID: string, connectorAPI?: ConnectorAPI, preflightMethods?: MethodRegistry): Promise<StartConnectorAuthOutput>;
-    completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteConnectorAuthOutput>;
+    completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteAuthResult>;
 }

package/lib/oauth.js

@@ -167,8 +167,11 @@ export class OAuthService {
             controllerWrappableDID: pending.controllerWrappableDID ?? undefined
         });
         return {
-            providerName: args.provider,
-            scopes
+            output: {
+                providerName: args.provider,
+                scopes
+            },
+            ownerDID: pending.ownerDID
         };
     }
 }

package/lib/periodic-sync.d.ts

@@ -0,0 +1,4 @@
+export declare function periodicSyncSubject(connector: string, ownerDID: string): {
+    owner: string;
+    subjectKey: string;
+};

package/lib/periodic-sync.js

@@ -0,0 +1,12 @@
+import { normalizeDID } from '@kokuin/token';
+// The adaptive schedule and the manual-sync singleton share one subject so a
+// scheduled run and a manual trigger interlock. Both fold the owner to its short
+// form first: credential rows and sync-state rows are keyed on the normalized
+// DID, and a viewer can arrive long-form (a mutation's `iss`).
+export function periodicSyncSubject(connector, ownerDID) {
+    const owner = normalizeDID(ownerDID);
+    return {
+        owner,
+        subjectKey: `${connector}:${owner}`
+    };
+}

package/lib/schema.d.ts

@@ -1,7 +1,8 @@
 import type { ConnectorSyncEventPayload } from '@kubun/connector';
 import type { SchemaExtension } from '@kubun/engine';
 import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
-import type { EventEmitter } from '@sozai/event';
+import type { EventEmitter, EventsSource } from '@sozai/event';
+import type { ConnectorLifecycleEventName, ConnectorLifecycleEventPayload } from './manager.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { SignedDocumentWriter } from './sync/processor.js';
 /**
@@ -19,6 +20,7 @@ export type ConnectorState = {
     lastSyncedAt: string | null;
     entityCount: number | null;
     error: string | null;
+    workflowStatusError: 'WORKFLOW_UNAVAILABLE' | null;
 };
 /**
  * Input/output types for connector auth mutations.
@@ -139,6 +141,47 @@ export type ConnectorSyncEventEmitter = EventEmitter<{
  * potentially never.
  */
 export declare function subscribeToConnectorSyncEvents(emitter: ConnectorSyncEventEmitter, connector?: string | null): AsyncIterableIterator<ConnectorSyncEventResult>;
+/**
+ * Merged lifecycle event payload for subscriptions (GraphQL result type). Flat
+ * and nullable: a given event carries only the fields its variant defines, and
+ * the rest resolve to null (mirrors `ConnectorSyncEventResult`).
+ */
+export type ConnectorLifecycleEventResult = {
+    type: ConnectorLifecycleEventName;
+    ownerDID: string;
+    provider: string | null;
+    connector: string | null;
+    connectors: Array<string> | null;
+    scopes: Array<string> | null;
+    expiresAt: number | null;
+    reason: string | null;
+    subjectKey: string | null;
+};
+/**
+ * Flatten a merged lifecycle payload into the GraphQL result shape, filling the
+ * fields absent from the variant with null.
+ */
+export declare function toConnectorLifecycleEventResult(event: ConnectorLifecycleEventPayload): ConnectorLifecycleEventResult;
+/**
+ * Subscribe to the merged lifecycle channel as a single viewer, yielding GraphQL
+ * result shapes. Every event is filtered by `ownerDID` against the caller's
+ * already-normalized `viewerDID`, so one viewer never observes another's auth
+ * activity; an optional `connector` further restricts delivery, matching both
+ * the auth-family `connectors[]` membership and the periodicSync single
+ * `connector`. Built on the same manual async iterator as
+ * `subscribeToConnectorSyncEvents` so a consumer's `return()` removes the
+ * emitter listener immediately rather than leaking behind a parked read.
+ *
+ * The emitter is the manager's listen-only `EventsSource`; `fromEmitter` only
+ * reads its `.on`, but its parameter is typed to the concrete emitter class, so
+ * the source is narrowed to it here.
+ */
+export declare function subscribeToConnectorLifecycleEvents(emitter: EventsSource<{
+    lifecycle: ConnectorLifecycleEventPayload;
+}>, opts: {
+    viewerDID: string;
+    connector?: string | null;
+}): AsyncIterableIterator<ConnectorLifecycleEventResult>;
 /**
  * Per-request context methods for the Connector query and mutation fields.
  * Provided by the context factory when registry + credentials are configured.
@@ -153,6 +196,7 @@ export type ConnectorQueryContext = {
     completeAuth: (args: CompleteConnectorAuthInput) => Promise<CompleteConnectorAuthOutput>;
     triggerSync: (args: SyncTriggerInput) => Promise<SyncTriggerOutput>;
     subscribeToSyncEvents: (connector?: string | null) => AsyncIterable<ConnectorSyncEventResult>;
+    subscribeToLifecycleEvents: (connector?: string | null) => AsyncIterable<ConnectorLifecycleEventResult>;
     executeAction?: (args: ConnectorActionInput, writeDocument: SignedDocumentWriter) => Promise<ConnectorActionResult>;
     grantWriteCapability?: (args: {
         connector: string;

package/lib/schema.js

@@ -58,6 +58,107 @@ import { fromEmitter } from '@sozai/generator';
         }
     };
 }
+/**
+ * Flatten a merged lifecycle payload into the GraphQL result shape, filling the
+ * fields absent from the variant with null.
+ */ export function toConnectorLifecycleEventResult(event) {
+    const result = {
+        type: event.type,
+        ownerDID: event.ownerDID,
+        provider: null,
+        connector: null,
+        connectors: null,
+        scopes: null,
+        expiresAt: null,
+        reason: null,
+        subjectKey: null
+    };
+    switch(event.type){
+        case 'connector:authenticated':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.scopes = event.scopes;
+            break;
+        case 'connector:deauthenticated':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            break;
+        case 'connector:credentialRefreshed':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.scopes = event.scopes;
+            result.expiresAt = event.expiresAt ?? null;
+            break;
+        case 'connector:authRequired':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.reason = event.reason;
+            break;
+        case 'periodicSync:enabled':
+        case 'periodicSync:disabled':
+            result.connector = event.connector;
+            result.subjectKey = event.subjectKey;
+            break;
+    }
+    return result;
+}
+/**
+ * Subscribe to the merged lifecycle channel as a single viewer, yielding GraphQL
+ * result shapes. Every event is filtered by `ownerDID` against the caller's
+ * already-normalized `viewerDID`, so one viewer never observes another's auth
+ * activity; an optional `connector` further restricts delivery, matching both
+ * the auth-family `connectors[]` membership and the periodicSync single
+ * `connector`. Built on the same manual async iterator as
+ * `subscribeToConnectorSyncEvents` so a consumer's `return()` removes the
+ * emitter listener immediately rather than leaking behind a parked read.
+ *
+ * The emitter is the manager's listen-only `EventsSource`; `fromEmitter` only
+ * reads its `.on`, but its parameter is typed to the concrete emitter class, so
+ * the source is narrowed to it here.
+ */ export function subscribeToConnectorLifecycleEvents(emitter, opts) {
+    const { viewerDID, connector } = opts;
+    const filter = (event)=>{
+        if (event.ownerDID !== viewerDID) {
+            return false;
+        }
+        if (connector == null) {
+            return true;
+        }
+        return 'connectors' in event ? event.connectors.includes(connector) : event.connector === connector;
+    };
+    const generator = fromEmitter(emitter, 'lifecycle', {
+        filter
+    });
+    return {
+        [Symbol.asyncIterator] () {
+            return this;
+        },
+        async next () {
+            const { done, value } = await generator.next();
+            return done ? {
+                done: true,
+                value: undefined
+            } : {
+                done: false,
+                value: toConnectorLifecycleEventResult(value)
+            };
+        },
+        async return () {
+            await generator.return();
+            return {
+                done: true,
+                value: undefined
+            };
+        },
+        async throw (reason) {
+            await generator.throw(reason);
+            return {
+                done: true,
+                value: undefined
+            };
+        }
+    };
+}
 function requireConnector(ctx) {
     if (ctx.connector == null) {
         throw new Error('connector plugin is not wired into this context');
@@ -116,6 +217,7 @@ type Connector implements Node {
   lastSyncedAt: String
   entityCount: Int
   error: String
+  workflowStatusError: String
 }
 
 type StartConnectorAuthResult {
@@ -144,6 +246,18 @@ type ConnectorSyncEvent {
   error: String
 }
 
+type ConnectorLifecycleEvent {
+  type: String!
+  ownerDID: String!
+  provider: String
+  connector: String
+  connectors: [String!]
+  scopes: [String!]
+  expiresAt: Float
+  reason: String
+  subjectKey: String
+}
+
 type ConnectorActionError {
   code: String!
   message: String!
@@ -175,6 +289,7 @@ extend type Mutation {
 
 extend type Subscription {
   connectorSyncEvents(connector: String): ConnectorSyncEvent!
+  connectorLifecycleEvents(connector: String): ConnectorLifecycleEvent!
 }
 `);
     // Recurring-sync control. Gated because it references `PeriodicSync`, which is
@@ -398,6 +513,13 @@ input ConnectorUpdate${modelName}Input {
                 const ctx = context;
                 return requireConnector(ctx).subscribeToSyncEvents(args.connector);
             }
+        },
+        connectorLifecycleEvents: {
+            resolve: (event)=>event,
+            subscribe: (_source, args, context)=>{
+                const ctx = context;
+                return requireConnector(ctx).subscribeToLifecycleEvents(args.connector);
+            }
         }
     };
     return {

package/lib/sync/orchestrate.d.ts

@@ -10,7 +10,7 @@ import type { MutateDocuments } from './processor.js';
  * this type can be replaced with the concrete class.
  */
 export type SyncEventEmitter = {
-    emitSyncEvent(event: ConnectorSyncEventPayload): Promise<void>;
+    emitSyncEvent(event: ConnectorSyncEventPayload): void;
 };
 export type OrchestrateSyncParams = {
     connectorName: string;
@@ -33,6 +33,16 @@ export type OrchestrateSyncParams = {
      * imports upsert by unique key).
      */
     inFlight?: Set<string>;
+    /**
+     * Signal that this sync bailed because the provider credential is absent, so a
+     * consumer can prompt (re)authorization. Additive to the sync `error` event —
+     * not a replacement. Fired only for a missing credential, never for an absent
+     * server provider.
+     */
+    emitAuthRequired?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 export type OrchestrateSyncResult = {
     status: 'started' | 'already_syncing' | 'error';

package/lib/sync/orchestrate.js

@@ -1,15 +1,40 @@
 import { SyncEngine } from './engine.js';
 export async function orchestrateSync(params) {
     const { connectorName, full, registry, syncEventEmitter, stateStore, credentialProvider, ownerDID, stores, inFlight, logger } = params;
+    // A failed emission must never escape as an unhandled rejection. The event
+    // emitter rejects `emit()` when any subscriber throws, and these emits are
+    // either awaited on a bail path (where a throw would divert into the outer
+    // catch and deliver a second, misleading error) or floated on the
+    // fire-and-forget run chain (where a throw would crash a strict host). Swallow
+    // and log, so a misbehaving subscriber cannot corrupt the sync's own signalling.
+    const safeEmit = async (event)=>{
+        try {
+            await syncEventEmitter.emitSyncEvent(event);
+        } catch (err) {
+            logger.warn('connector sync event delivery failed {connectorName}', {
+                connectorName,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    };
+    // A failed sync must be observable. Every bail below emits an `error` event so a
+    // subscriber sees the failure instead of silence — a swallowed failure here
+    // starves concurrent connectors that never learn their sync was dropped.
+    const emitError = (error)=>safeEmit({
+            type: 'error',
+            connectorName,
+            error
+        });
     const connector = registry.get(connectorName);
     if (connector == null) {
+        await emitError('connector is not registered');
         return {
             status: 'error'
         };
     }
     // Reserve the (connector, owner) synchronously — before any await — so two
     // concurrent triggers cannot both pass the check. Released once the run
-    // settles (or here on any early bail).
+    // settles (or on any early bail).
     const guardKey = `${connectorName}:${ownerDID}`;
     if (inFlight != null) {
         if (inFlight.has(guardKey)) {
@@ -20,86 +45,103 @@ export async function orchestrateSync(params) {
         inFlight.add(guardKey);
     }
     const release = ()=>inFlight?.delete(guardKey);
-    // Get credentials for OAuth connectors
-    const providerName = connector.auth.provider !== 'device' ? connector.auth.provider : null;
-    const credential = providerName ? await credentialProvider.get(providerName, ownerDID) : null;
-    if (providerName != null && credential == null) {
-        release();
+    // Everything from the reservation to the engine handoff runs under one guard:
+    // any throw here (credential fetch, provider construction, the started emit)
+    // must release the reservation, or the guard would wedge every later sync into
+    // a silent `already_syncing`. The engine promise's own `.finally(release)` owns
+    // the guard only once `run()` has been handed off.
+    try {
+        // Get credentials for OAuth connectors
+        const providerName = connector.auth.provider !== 'device' ? connector.auth.provider : null;
+        const credential = providerName ? await credentialProvider.get(providerName, ownerDID) : null;
+        if (providerName != null && credential == null) {
+            release();
+            // Additive to the error event below: the sync stream still sees the failure,
+            // and a lifecycle consumer additionally learns (re)authorization is needed.
+            params.emitAuthRequired?.({
+                provider: providerName,
+                ownerDID
+            });
+            await emitError(`no credential for provider "${providerName}"`);
+            return {
+                status: 'error'
+            };
+        }
+        // Ensure server provider is available
+        if (connector.serverProvider == null) {
+            release();
+            await emitError('connector has no server provider');
+            return {
+                status: 'error'
+            };
+        }
+        const effectiveBoundary = params.boundary ?? {
+            maxAge: 'P90D'
+        };
+        const provider = connector.serverProvider({
+            credential: credential ?? {
+                accessToken: '',
+                scopes: []
+            },
+            boundary: effectiveBoundary
+        });
+        const engine = new SyncEngine({
+            stores,
+            stateStore,
+            connectorName,
+            clusters: connector.clusters,
+            logger,
+            mutateDocuments: params.mutateDocuments
+        });
+        // Emit started event
+        await safeEmit({
+            type: 'started',
+            connectorName
+        });
+        // Bridge engine events to sync event emitter
+        engine.on('sync', (event)=>{
+            if (event.type === 'sync:progress') {
+                void safeEmit({
+                    type: 'progress',
+                    connectorName,
+                    entitiesProcessed: event.entitiesProcessed,
+                    entitiesFailed: event.entitiesFailed
+                });
+            } else if (event.type === 'sync:complete') {
+                void safeEmit({
+                    type: 'completed',
+                    connectorName,
+                    totalProcessed: event.totalProcessed,
+                    totalFailed: event.totalFailed,
+                    duration: event.duration,
+                    failedSample: event.failedSample
+                });
+            } else if (event.type === 'sync:error') {
+                void safeEmit({
+                    type: 'error',
+                    connectorName,
+                    error: event.error,
+                    failedSample: event.failedSample
+                });
+            }
+        });
+        // Run sync (fire-and-forget — mutation returns immediately)
+        engine.run({
+            provider,
+            ownerDID,
+            boundary: effectiveBoundary,
+            full
+        }).catch((err)=>emitError(err instanceof Error ? err.message : String(err))).finally(release);
         return {
-            status: 'error'
+            status: 'started'
         };
-    }
-    // Ensure server provider is available
-    if (connector.serverProvider == null) {
+    } catch (err) {
+        // A pre-handoff throw: the engine never took ownership of the guard, so
+        // release it here and surface the failure.
         release();
+        await emitError(err instanceof Error ? err.message : String(err));
         return {
             status: 'error'
         };
     }
-    const effectiveBoundary = params.boundary ?? {
-        maxAge: 'P90D'
-    };
-    const provider = connector.serverProvider({
-        credential: credential ?? {
-            accessToken: '',
-            scopes: []
-        },
-        boundary: effectiveBoundary
-    });
-    const engine = new SyncEngine({
-        stores,
-        stateStore,
-        connectorName,
-        clusters: connector.clusters,
-        logger,
-        mutateDocuments: params.mutateDocuments
-    });
-    // Emit started event
-    await syncEventEmitter.emitSyncEvent({
-        type: 'started',
-        connectorName
-    });
-    // Bridge engine events to sync event emitter
-    engine.on('sync', (event)=>{
-        if (event.type === 'sync:progress') {
-            syncEventEmitter.emitSyncEvent({
-                type: 'progress',
-                connectorName,
-                entitiesProcessed: event.entitiesProcessed,
-                entitiesFailed: event.entitiesFailed
-            });
-        } else if (event.type === 'sync:complete') {
-            syncEventEmitter.emitSyncEvent({
-                type: 'completed',
-                connectorName,
-                totalProcessed: event.totalProcessed,
-                totalFailed: event.totalFailed,
-                duration: event.duration,
-                failedSample: event.failedSample
-            });
-        } else if (event.type === 'sync:error') {
-            syncEventEmitter.emitSyncEvent({
-                type: 'error',
-                connectorName,
-                error: event.error,
-                failedSample: event.failedSample
-            });
-        }
-    });
-    // Run sync (fire-and-forget — mutation returns immediately)
-    engine.run({
-        provider,
-        ownerDID,
-        boundary: effectiveBoundary,
-        full
-    }).catch(async (err)=>{
-        await syncEventEmitter.emitSyncEvent({
-            type: 'error',
-            connectorName,
-            error: err instanceof Error ? err.message : String(err)
-        });
-    }).finally(release);
-    return {
-        status: 'started'
-    };
 }

package/lib/sync/workflow.d.ts

@@ -33,6 +33,7 @@ export type ConnectorSyncWorkflowDefinition = {
         name: string;
     };
     handlers: Record<string, ConnectorSyncHandler>;
+    managed: true;
 };
 export type ConnectorSyncWorkflowParams = {
     registry: ConnectorRegistry;
@@ -43,6 +44,16 @@ export type ConnectorSyncWorkflowParams = {
     mutateDocuments?: MutateDocuments;
     boundary?: SyncBoundary;
     logger: Logger;
+    /**
+     * Signal that a sync cannot proceed because the provider credential is absent,
+     * so a consumer can prompt (re)authorization. Fired only for a genuinely
+     * missing credential — never for an absent server provider, which is an
+     * ordinary offline/configuration outcome.
+     */
+    emitAuthRequired?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 /**
  * Build the `connector-sync` workflow definition. One sync pass is a self-looping