@kubun/plugin-connector 0.14.1 → 0.14.2

package/lib/action.d.ts

@@ -34,5 +34,14 @@ export type ExecuteActionDeps = {
      * import binary content (e.g. a Gmail attachment) on demand.
      */
     writeAttachment?: WriteAttachment;
+    /**
+     * Signal that this action cannot run because the provider credential is absent,
+     * so a consumer can prompt (re)authorization. Fired only for a genuinely
+     * missing credential, alongside the thrown error the caller surfaces.
+     */
+    emitAuthRequired?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 export declare function executeAction(params: ExecuteActionParams, deps: ExecuteActionDeps): Promise<ExecuteActionResult>;

package/lib/action.js

@@ -2,7 +2,7 @@ import { DocumentID, DocumentModelID } from '@kubun/id';
 import { getGraphStore } from '@kubun/store-graph';
 import { EntityProcessor } from './sync/processor.js';
 export async function executeAction(params, deps) {
-    const { stores, registry, credentialProvider, ownerDID, logger, writeDocument, writeAttachment } = deps;
+    const { stores, registry, credentialProvider, ownerDID, logger, writeDocument, writeAttachment, emitAuthRequired } = deps;
     const { connector: connectorName, action: actionName, model: modelName, input, sourceID } = params;
     const connector = registry.get(connectorName);
     if (connector == null) {
@@ -19,6 +19,14 @@ export async function executeAction(params, deps) {
     const providerName = connector.auth.provider;
     const credential = await credentialProvider.get(providerName, ownerDID);
     if (credential == null) {
+        // A device connector carries no OAuth credential, so its absence is not an
+        // authorization gap — only a real provider asks for (re)authorization.
+        if (providerName !== 'device') {
+            emitAuthRequired?.({
+                provider: providerName,
+                ownerDID
+            });
+        }
         throw new Error(`No credential found for provider "${providerName}"`);
     }
     // Check write scopes

package/lib/auth-required.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectorAuthRequiredEvent } from './manager.js';
+import type { ConnectorRegistry } from './registry.js';
+/**
+ * Assemble the `connector:authRequired` payload for a genuinely missing
+ * credential: the provider's registered connectors, the owner folded to its
+ * normalized (short) form — the same folding the credential row is keyed on —
+ * and `reason: 'absent'`. The deep sync sites (workflow, orchestrate, action)
+ * only signal `{ provider, ownerDID }`; the connector mapping and normalization
+ * live here so those sites carry no manager or registry knowledge.
+ */
+export declare function connectorAuthRequiredPayload(registry: ConnectorRegistry, provider: string, ownerDID: string): ConnectorAuthRequiredEvent;

package/lib/auth-required.js

@@ -0,0 +1,17 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * Assemble the `connector:authRequired` payload for a genuinely missing
+ * credential: the provider's registered connectors, the owner folded to its
+ * normalized (short) form — the same folding the credential row is keyed on —
+ * and `reason: 'absent'`. The deep sync sites (workflow, orchestrate, action)
+ * only signal `{ provider, ownerDID }`; the connector mapping and normalization
+ * live here so those sites carry no manager or registry knowledge.
+ */ export function connectorAuthRequiredPayload(registry, provider, ownerDID) {
+    const connectors = registry.getAll().filter((connector)=>connector.auth.provider === provider).map((connector)=>connector.name);
+    return {
+        provider,
+        connectors,
+        ownerDID: normalizeDID(ownerDID),
+        reason: 'absent'
+    };
+}

package/lib/credential-refresh-bridge.d.ts

@@ -0,0 +1,11 @@
+import type { EventsSource } from '@sozai/event';
+import type { RefreshEvents } from './credential.js';
+import type { ConnectorManager } from './manager.js';
+import type { ConnectorRegistry } from './registry.js';
+export type BridgeCredentialRefreshEventsParams = {
+    source: EventsSource<RefreshEvents>;
+    manager: ConnectorManager;
+    registry: ConnectorRegistry;
+    defer: (fn: () => void) => void;
+};
+export declare function bridgeCredentialRefreshEvents(params: BridgeCredentialRefreshEventsParams): void;

package/lib/credential-refresh-bridge.js

@@ -0,0 +1,27 @@
+import { normalizeDID } from '@kokuin/token';
+export function bridgeCredentialRefreshEvents(params) {
+    const { source, manager, registry, defer } = params;
+    const connectorsFor = (provider)=>registry.getAll().filter((connector)=>connector.auth.provider === provider).map((connector)=>connector.name);
+    source.on('refreshed', ({ providerName, ownerDID, scopes, expiresAt })=>{
+        defer(()=>{
+            manager.emitLifecycle('connector:credentialRefreshed', {
+                provider: providerName,
+                connectors: connectorsFor(providerName),
+                ownerDID: normalizeDID(ownerDID),
+                scopes,
+                expiresAt: expiresAt?.getTime()
+            });
+        });
+    });
+    source.on('refreshFailed', ({ providerName, ownerDID, category })=>{
+        if (category !== 'invalid_grant') return;
+        defer(()=>{
+            manager.emitLifecycle('connector:authRequired', {
+                provider: providerName,
+                connectors: connectorsFor(providerName),
+                ownerDID: normalizeDID(ownerDID),
+                reason: 'invalid_grant'
+            });
+        });
+    });
+}

package/lib/credential.d.ts

@@ -1,2 +1,2 @@
-export type { DBCredentialProviderParams } from '@kubun/credential';
-export { DBCredentialProvider } from '@kubun/credential';
+export type { DBCredentialProviderParams, RefreshEvents, RefreshingCredentialProviderParams, RefreshOutcome, } from '@kubun/credential';
+export { DBCredentialProvider, RefreshingCredentialProvider } from '@kubun/credential';

package/lib/credential.js

@@ -1,4 +1,4 @@
 // The DB-backed credential provider moved to @kubun/credential; re-exported here
 // so existing importers of `../src/credential.js` and the package index keep
 // resolving it.
-export { DBCredentialProvider } from '@kubun/credential';
+export { DBCredentialProvider, RefreshingCredentialProvider } from '@kubun/credential';

package/lib/index.d.ts

@@ -2,8 +2,10 @@ import type { ConnectorDefinition, SyncBoundary } from '@kubun/connector';
 import type { OAuthProviderDefinition } from '@kubun/credential-types';
 import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
 import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
+import type { EventsSource } from '@sozai/event';
 import { type ConnectorAPI, type CredentialAPI, type SetSyncStateParams, type SyncStateData } from './api.js';
-import { DBCredentialProvider, type DBCredentialProviderParams } from './credential.js';
+import { DBCredentialProvider, type DBCredentialProviderParams, RefreshingCredentialProvider, type RefreshingCredentialProviderParams } from './credential.js';
+import { type ConnectorManagerEvents } from './manager.js';
 export { type ExecuteActionDeps, type ExecuteActionParams, type ExecuteActionResult, executeAction, } from './action.js';
 export { type ConnectorActivatedEvent, type ConnectorDeactivatedEvent, ConnectorManager, type ConnectorManagerEvents, type ConnectorManagerParams, } from './manager.js';
 export { OAuthService, type OAuthServiceParams } from './oauth.js';
@@ -16,7 +18,10 @@ export { EntityProcessor, type EntityProcessorParams, type MutateDocuments, type
 export { DBSyncStateStore } from './sync/state.js';
 export { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, type ConnectorSyncWorkflowDefinition, type ConnectorSyncWorkflowParams, createConnectorSyncWorkflow, } from './sync/workflow.js';
 export type { ConnectorAPI, CredentialAPI, SetSyncStateParams, SyncStateData };
-export { DBCredentialProvider, type DBCredentialProviderParams };
+export type ConnectorPluginAPI = ConnectorAPI & {
+    events: EventsSource<ConnectorManagerEvents>;
+};
+export { DBCredentialProvider, type DBCredentialProviderParams, RefreshingCredentialProvider, type RefreshingCredentialProviderParams, };
 export type ConnectorPluginOptions = {
     connectors: Array<ConnectorDefinition>;
     providers?: Array<OAuthProviderDefinition>;
@@ -24,5 +29,6 @@ export type ConnectorPluginOptions = {
         boundary?: SyncBoundary;
         periodicSyncPolicy?: AdaptivePolicy;
     };
+    autoEnablePeriodicSync?: boolean;
 };
 export declare function createConnectorPlugin(options: ConnectorPluginOptions): (params: PluginFactoryParams) => KubunPlugin;