@kubun/plugin-connector 0.10.0 → 0.11.0

package/lib/action.d.ts

@@ -1,6 +1,8 @@
 import type { CredentialProvider, EntityRecord } from '@kubun/connector';
 import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
 import type { ConnectorRegistry } from './registry.js';
+import { type SignedDocumentWriter } from './sync/processor.js';
 export type ExecuteActionParams = {
     connector: string;
     action: string;
@@ -17,5 +19,13 @@ export type ExecuteActionDeps = {
     registry: ConnectorRegistry;
     credentialProvider: CredentialProvider;
     ownerDID: string;
+    logger: Logger;
+    /**
+     * Signs and applies the action's resulting document as `ownerDID` (the
+     * viewer) through the mutation pipeline. The action runs inside the request's
+     * mutation transaction, so this must use the in-transaction signed-set seam
+     * rather than opening a nested transaction.
+     */
+    writeDocument: SignedDocumentWriter;
 };
 export declare function executeAction(params: ExecuteActionParams, deps: ExecuteActionDeps): Promise<ExecuteActionResult>;

package/lib/action.js

@@ -1 +1,106 @@
-import{DocumentID as e,DocumentModelID as r}from"@kubun/id";import{getGraphStore as o}from"@kubun/store-graph";import{EntityProcessor as t}from"./sync/processor.js";export async function executeAction(n,l){let c,i,{stores:a,registry:u,credentialProvider:s,ownerDID:d}=l,{connector:f,action:p,model:w,input:m,sourceID:E}=n,h=u.get(f);if(null==h)throw Error(`Connector "${f}" not found`);if(null==h.actionHandler)throw Error(`Connector "${f}" does not support actions`);if(null==h.actions?.find(e=>e.name===p))throw Error(`Action "${p}" not found on connector "${f}"`);let S=h.auth.provider,$=await s.get(S,d);if(null==$)throw Error(`No credential found for provider "${S}"`);let I=h.auth;if(null!=I.writeScopes&&!I.writeScopes.every(e=>$.scopes.includes(e))){let e=Error("INSUFFICIENT_SCOPES");throw e.code="INSUFFICIENT_SCOPES",e.requiredScopes=I.writeScopes,e}for(let e of Object.values(h.clusters)){for(let[r,o]of Object.entries(e.record))if(e.models[o].name===w){c=r;break}if(null!=c)break}if(null==c)throw Error(`Model "${w}" not found in connector "${f}" clusters`);let b=m;if("update"===p&&null!=E){let t=new TextEncoder().encode(`${f}:${E}`),n=e.create(r.fromString(c),d,t),l=await o(a),i=await l.getDocument(n);i?.data!=null&&(b={...i.data,...m})}let C=h.actionHandler({credential:$});if("create"===p)i=await C.create(w,b);else if("update"===p){if(null==E)throw Error("sourceID is required for update actions");i=await C.update(w,E,b)}else throw Error(`Unsupported action: ${p}`);let g={};for(let e of Object.values(h.clusters))if(null!=e.record[c]){g=e.models[e.record[c]]?.fieldsMeta??{};break}let k=new t({stores:a,modelID:c,ownerDID:d,connectorName:f,edgeFields:g,clusters:h.clusters}),v=await k.processBatch({entities:[i]});return{entity:i,documentID:v.documentIDs[0]??null}}
+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 } = deps;
+    const { connector: connectorName, action: actionName, model: modelName, input, sourceID } = params;
+    const connector = registry.get(connectorName);
+    if (connector == null) {
+        throw new Error(`Connector "${connectorName}" not found`);
+    }
+    if (connector.actionHandler == null) {
+        throw new Error(`Connector "${connectorName}" does not support actions`);
+    }
+    const action = connector.actions?.find((a)=>a.name === actionName);
+    if (action == null) {
+        throw new Error(`Action "${actionName}" not found on connector "${connectorName}"`);
+    }
+    // Fetch credential
+    const providerName = connector.auth.provider;
+    const credential = await credentialProvider.get(providerName, ownerDID);
+    if (credential == null) {
+        throw new Error(`No credential found for provider "${providerName}"`);
+    }
+    // Check write scopes
+    const auth = connector.auth;
+    if (auth.writeScopes != null) {
+        const hasWriteScopes = auth.writeScopes.every((scope)=>credential.scopes.includes(scope));
+        if (!hasWriteScopes) {
+            const error = new Error('INSUFFICIENT_SCOPES');
+            error.code = 'INSUFFICIENT_SCOPES';
+            error.requiredScopes = auth.writeScopes;
+            throw error;
+        }
+    }
+    // Resolve model ID from clusters
+    let modelID;
+    for (const cluster of Object.values(connector.clusters)){
+        for (const [id, index] of Object.entries(cluster.record)){
+            const model = cluster.models[index];
+            if (model.name === modelName) {
+                modelID = id;
+                break;
+            }
+        }
+        if (modelID != null) break;
+    }
+    if (modelID == null) {
+        throw new Error(`Model "${modelName}" not found in connector "${connectorName}" clusters`);
+    }
+    // For updates, merge contextual fields from existing document (e.g., calendarID)
+    let mergedInput = input;
+    if (actionName === 'update' && sourceID != null) {
+        const uniqueBytes = new TextEncoder().encode(`${connectorName}:${sourceID}`);
+        const docID = DocumentID.create(DocumentModelID.fromString(modelID), ownerDID, uniqueBytes);
+        const graphStore = await getGraphStore(stores);
+        const existingDoc = await graphStore.getDocument(docID);
+        if (existingDoc?.data != null) {
+            mergedInput = {
+                ...existingDoc.data,
+                ...input
+            };
+        }
+    }
+    // Dispatch to provider's action handler
+    const handler = connector.actionHandler({
+        credential
+    });
+    let entity;
+    if (actionName === 'create') {
+        entity = await handler.create(modelName, mergedInput);
+    } else if (actionName === 'update') {
+        if (sourceID == null) {
+            throw new Error('sourceID is required for update actions');
+        }
+        entity = await handler.update(modelName, sourceID, mergedInput);
+    } else {
+        throw new Error(`Unsupported action: ${actionName}`);
+    }
+    // Process entity into Kubun document via EntityProcessor
+    let edgeFields = {};
+    for (const cluster of Object.values(connector.clusters)){
+        if (cluster.record[modelID] != null) {
+            edgeFields = cluster.models[cluster.record[modelID]]?.fieldsMeta ?? {};
+            break;
+        }
+    }
+    const processor = new EntityProcessor({
+        stores,
+        modelID,
+        ownerDID,
+        connectorName,
+        logger,
+        edgeFields,
+        clusters: connector.clusters,
+        writeDocument
+    });
+    const result = await processor.processBatch({
+        entities: [
+            entity
+        ]
+    });
+    return {
+        entity,
+        documentID: result.documentIDs[0] ?? null
+    };
+}

package/lib/api.d.ts

@@ -1,4 +1,6 @@
 import type { StoreProvider } from '@kubun/db';
+import type { Cipher } from '@kubun/engine';
+import { type PendingAuthRecord } from '@kubun/store-connector';
 export type SyncStateData = {
     connectorName: string;
     ownerDID: string;
@@ -7,6 +9,7 @@ export type SyncStateData = {
     entityCount: number;
     status: string;
     error: string | null;
+    leaseExpiresAt: number | null;
 };
 export type SetSyncStateParams = {
     checkpoint?: string | null;
@@ -20,10 +23,16 @@ export type ConnectorAPI = {
     setSyncState: (connectorName: string, ownerDID: string, state: SetSyncStateParams) => Promise<SyncStateData>;
     deleteSyncState: (connectorName: string, ownerDID: string) => Promise<void>;
     listSyncStates: (connectorName: string) => Promise<Array<SyncStateData>>;
+    claimSync: (connectorName: string, ownerDID: string, leaseMs: number) => Promise<boolean>;
+    renewSync: (connectorName: string, ownerDID: string, leaseMs: number) => Promise<void>;
     getCredential: (providerName: string, ownerDID: string) => Promise<string | null>;
     setCredential: (providerName: string, ownerDID: string, credential: string) => Promise<void>;
     deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
+    createPendingAuth: (record: PendingAuthRecord) => Promise<void>;
+    consumePendingAuth: (state: string) => Promise<PendingAuthRecord | null>;
+    deleteExpiredPendingAuth: (cutoffMs: number) => Promise<void>;
 };
 export declare function createConnectorAPI(params: {
     stores: StoreProvider;
+    cipher: Cipher | undefined;
 }): ConnectorAPI;

package/lib/api.js

@@ -1 +1,108 @@
-import{getConnectorStore as t}from"@kubun/store-connector";export function createConnectorAPI(e){return{async getSyncState(n,a){let r=await t(e.stores),s=await r.getSyncState(n,a);return null==s?null:{connectorName:n,ownerDID:a,checkpoint:null!=s.checkpoint?JSON.stringify(s.checkpoint):null,lastSyncedAt:s.lastSyncedAt,entityCount:s.entityCount,status:s.status,error:s.error??null}},async setSyncState(n,a,r){let s=await t(e.stores),c=r.lastSyncedAt??new Date().toISOString(),o=r.entityCount??0,l=r.checkpoint??null;await s.setSyncState(n,a,{checkpoint:null!=l?JSON.parse(l):null,lastSyncedAt:c,entityCount:o,status:r.status,error:r.error??void 0});let i=await s.getSyncState(n,a);if(null==i)throw Error("Failed to set sync state");return{connectorName:n,ownerDID:a,checkpoint:null!=i.checkpoint?JSON.stringify(i.checkpoint):null,lastSyncedAt:i.lastSyncedAt,entityCount:i.entityCount,status:i.status,error:i.error??null}},async deleteSyncState(n,a){let r=await t(e.stores);await r.deleteSyncState(n,a)},async listSyncStates(n){let a=await t(e.stores);return(await a.listSyncStatesForConnector(n)).map(t=>({connectorName:t.connectorName,ownerDID:t.ownerDID,checkpoint:null!=t.checkpoint?JSON.stringify(t.checkpoint):null,lastSyncedAt:t.lastSyncedAt,entityCount:t.entityCount,status:t.status,error:t.error??null}))},async getCredential(n,a){let r=await t(e.stores),s=await r.getCredential(n,a);return null==s?null:"string"==typeof s?s:JSON.stringify({accessToken:s.accessToken,refreshToken:s.refreshToken,expiresAt:s.expiresAt?.toISOString(),scopes:s.scopes,accountLabel:s.accountLabel,metadata:s.metadata})},async setCredential(n,a,r){let s=await t(e.stores);await s.setCredential(n,a,r)},async deleteCredential(n,a){let r=await t(e.stores);await r.deleteCredential(n,a)}}}
+import { getConnectorStore } from '@kubun/store-connector';
+// ---- Factory ----
+export function createConnectorAPI(params) {
+    const getStore = ()=>getConnectorStore(params.stores);
+    const cipher = params.cipher;
+    return {
+        async getSyncState (connectorName, ownerDID) {
+            const store = await getStore();
+            const state = await store.getSyncState(connectorName, ownerDID);
+            if (state == null) return null;
+            return {
+                connectorName,
+                ownerDID,
+                checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+                lastSyncedAt: state.lastSyncedAt,
+                entityCount: state.entityCount,
+                status: state.status,
+                error: state.error ?? null,
+                leaseExpiresAt: state.leaseExpiresAt ?? null
+            };
+        },
+        async setSyncState (connectorName, ownerDID, state) {
+            const store = await getStore();
+            const lastSyncedAt = state.lastSyncedAt ?? new Date().toISOString();
+            const entityCount = state.entityCount ?? 0;
+            const checkpoint = state.checkpoint ?? null;
+            await store.setSyncState(connectorName, ownerDID, {
+                checkpoint: checkpoint != null ? JSON.parse(checkpoint) : null,
+                lastSyncedAt,
+                entityCount,
+                status: state.status,
+                error: state.error ?? undefined
+            });
+            const saved = await store.getSyncState(connectorName, ownerDID);
+            if (saved == null) {
+                throw new Error('Failed to set sync state');
+            }
+            return {
+                connectorName,
+                ownerDID,
+                checkpoint: saved.checkpoint != null ? JSON.stringify(saved.checkpoint) : null,
+                lastSyncedAt: saved.lastSyncedAt,
+                entityCount: saved.entityCount,
+                status: saved.status,
+                error: saved.error ?? null,
+                leaseExpiresAt: saved.leaseExpiresAt ?? null
+            };
+        },
+        async deleteSyncState (connectorName, ownerDID) {
+            const store = await getStore();
+            await store.deleteSyncState(connectorName, ownerDID);
+        },
+        async listSyncStates (connectorName) {
+            const store = await getStore();
+            const entries = await store.listSyncStatesForConnector(connectorName);
+            return entries.map((entry)=>({
+                    connectorName: entry.connectorName,
+                    ownerDID: entry.ownerDID,
+                    checkpoint: entry.checkpoint != null ? JSON.stringify(entry.checkpoint) : null,
+                    lastSyncedAt: entry.lastSyncedAt,
+                    entityCount: entry.entityCount,
+                    status: entry.status,
+                    error: entry.error ?? null,
+                    leaseExpiresAt: entry.leaseExpiresAt ?? null
+                }));
+        },
+        async claimSync (connectorName, ownerDID, leaseMs) {
+            const store = await getStore();
+            return store.claimSync(connectorName, ownerDID, leaseMs);
+        },
+        async renewSync (connectorName, ownerDID, leaseMs) {
+            const store = await getStore();
+            await store.renewSync(connectorName, ownerDID, leaseMs);
+        },
+        async getCredential (providerName, ownerDID) {
+            const store = await getStore();
+            const stored = await store.getCredential(providerName, ownerDID);
+            if (stored == null) return null;
+            if (cipher == null) {
+                throw new Error('Cannot decrypt connector credential: no at-rest cipher available');
+            }
+            return cipher.decrypt(stored);
+        },
+        async setCredential (providerName, ownerDID, credential) {
+            if (cipher == null) {
+                throw new Error('Cannot persist connector credential: no at-rest cipher available');
+            }
+            const store = await getStore();
+            await store.setCredential(providerName, ownerDID, cipher.encrypt(credential));
+        },
+        async deleteCredential (providerName, ownerDID) {
+            const store = await getStore();
+            await store.deleteCredential(providerName, ownerDID);
+        },
+        async createPendingAuth (record) {
+            const store = await getStore();
+            await store.createPendingAuth(record);
+        },
+        async consumePendingAuth (state) {
+            const store = await getStore();
+            return store.consumePendingAuth(state);
+        },
+        async deleteExpiredPendingAuth (cutoffMs) {
+            const store = await getStore();
+            await store.deleteExpiredPendingAuth(cutoffMs);
+        }
+    };
+}

package/lib/boundary.js

@@ -1 +1,73 @@
-let e=/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;export function parseDuration(n){let i=e.exec(n);if(!i)return;let t=Number.parseInt(i[1]??"0",10),l=Number.parseInt(i[2]??"0",10),a=Number.parseInt(i[3]??"0",10),u=Number.parseInt(i[4]??"0",10);if(0!==t||0!==l||0!==a||0!==u)return((24*t+l)*60+a)*6e4+1e3*u}export function computeEffectiveBoundary(e,n){if(null==n)return e;let i={};if(null!=e.maxAge||null!=n.maxAge){let t=e.maxAge?parseDuration(e.maxAge):void 0,l=n.maxAge?parseDuration(n.maxAge):void 0;null!=t&&null!=l?i.maxAge=t<=l?e.maxAge:n.maxAge:i.maxAge=e.maxAge??n.maxAge}if(null!=e.since||null!=n.since){let t=e.since?new Date(e.since):void 0,l=n.since?new Date(n.since):void 0;null!=t&&null!=l?i.since=t>=l?e.since:n.since:i.since=e.since??n.since}if(null!=e.maxEntities||null!=n.maxEntities){let t=e.maxEntities,l=n.maxEntities;null!=t&&null!=l?i.maxEntities=Math.min(t,l):i.maxEntities=e.maxEntities??n.maxEntities}return i}export function isWithinBoundary(e,n){let i=Date.now();if(null!=n.maxAge){let t=parseDuration(n.maxAge);if(null!=t&&e.getTime()<i-t)return!1}if(null!=n.since){let i=new Date(n.since);if(e.getTime()<i.getTime())return!1}return!0}
+const DURATION_REGEX = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+export function parseDuration(duration) {
+    const match = DURATION_REGEX.exec(duration);
+    if (!match) {
+        return undefined;
+    }
+    const days = Number.parseInt(match[1] ?? '0', 10);
+    const hours = Number.parseInt(match[2] ?? '0', 10);
+    const minutes = Number.parseInt(match[3] ?? '0', 10);
+    const seconds = Number.parseInt(match[4] ?? '0', 10);
+    if (days === 0 && hours === 0 && minutes === 0 && seconds === 0) {
+        return undefined;
+    }
+    return ((days * 24 + hours) * 60 + minutes) * 60 * 1000 + seconds * 1000;
+}
+export function computeEffectiveBoundary(serverBoundary, userBoundary) {
+    if (userBoundary == null) {
+        return serverBoundary;
+    }
+    const result = {};
+    // maxAge: take the shorter duration (more restrictive)
+    if (serverBoundary.maxAge != null || userBoundary.maxAge != null) {
+        const serverMs = serverBoundary.maxAge ? parseDuration(serverBoundary.maxAge) : undefined;
+        const userMs = userBoundary.maxAge ? parseDuration(userBoundary.maxAge) : undefined;
+        if (serverMs != null && userMs != null) {
+            result.maxAge = serverMs <= userMs ? serverBoundary.maxAge : userBoundary.maxAge;
+        } else {
+            result.maxAge = serverBoundary.maxAge ?? userBoundary.maxAge;
+        }
+    }
+    // since: take the more recent date (more restrictive)
+    if (serverBoundary.since != null || userBoundary.since != null) {
+        const serverDate = serverBoundary.since ? new Date(serverBoundary.since) : undefined;
+        const userDate = userBoundary.since ? new Date(userBoundary.since) : undefined;
+        if (serverDate != null && userDate != null) {
+            result.since = serverDate >= userDate ? serverBoundary.since : userBoundary.since;
+        } else {
+            result.since = serverBoundary.since ?? userBoundary.since;
+        }
+    }
+    // maxEntities: take the smaller count (more restrictive)
+    if (serverBoundary.maxEntities != null || userBoundary.maxEntities != null) {
+        const serverCount = serverBoundary.maxEntities;
+        const userCount = userBoundary.maxEntities;
+        if (serverCount != null && userCount != null) {
+            result.maxEntities = Math.min(serverCount, userCount);
+        } else {
+            result.maxEntities = serverBoundary.maxEntities ?? userBoundary.maxEntities;
+        }
+    }
+    return result;
+}
+export function isWithinBoundary(date, boundary) {
+    const now = Date.now();
+    // Check maxAge constraint
+    if (boundary.maxAge != null) {
+        const maxAgeMs = parseDuration(boundary.maxAge);
+        if (maxAgeMs != null) {
+            const cutoff = now - maxAgeMs;
+            if (date.getTime() < cutoff) {
+                return false;
+            }
+        }
+    }
+    // Check since constraint
+    if (boundary.since != null) {
+        const sinceDate = new Date(boundary.since);
+        if (date.getTime() < sinceDate.getTime()) {
+            return false;
+        }
+    }
+    return true;
+}

package/lib/credential.d.ts

@@ -1,5 +1,5 @@
-import type { Runtime } from '@enkaku/runtime';
 import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
+import type { Runtime } from '@sozai/runtime';
 import type { ConnectorAPI } from './api.js';
 export type DBCredentialProviderParams = {
     api: ConnectorAPI;

package/lib/credential.js

@@ -1 +1,107 @@
-export class DBCredentialProvider{#e;#t;#n;#r;constructor(e){this.#e=e.api,this.#t=e.runtime,this.#n=e.providers,this.#r=(e.bufferSeconds??300)*1e3}async get(e,t){let n,r,s=await this.#e.getCredential(e,t);if(null==s)return null;let a=(r={accessToken:(n="string"==typeof s?JSON.parse(s):s).accessToken,scopes:n.scopes},null!=n.refreshToken&&(r.refreshToken=n.refreshToken),null!=n.expiresAt&&(r.expiresAt=new Date(n.expiresAt)),null!=n.accountLabel&&(r.accountLabel=n.accountLabel),null!=n.metadata&&(r.metadata=n.metadata),r);return this.#s(a)&&null!=a.refreshToken?await this.#a(e,t,a,a.refreshToken)??a:a}async set(e,t,n){let r;await this.#e.setCredential(e,t,(r={accessToken:n.accessToken,scopes:n.scopes},null!=n.refreshToken&&(r.refreshToken=n.refreshToken),null!=n.expiresAt&&(r.expiresAt=n.expiresAt.toISOString()),null!=n.accountLabel&&(r.accountLabel=n.accountLabel),null!=n.metadata&&(r.metadata=n.metadata),JSON.stringify(r)))}async delete(e,t){await this.#e.deleteCredential(e,t)}#s(e){return null!=e.expiresAt&&e.expiresAt.getTime()-Date.now()<this.#r}async #a(e,t,n,r){let s=this.#n.find(t=>t.name===e);if(null==s||null==s.clientID||null==s.clientSecret)return null;try{let a=await this.#t.fetch(s.tokenEndpoint,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"refresh_token",refresh_token:r,client_id:s.clientID,client_secret:s.clientSecret})});if(!a.ok)return null;let i=await a.json(),l={accessToken:i.access_token,refreshToken:i.refresh_token??n.refreshToken,expiresAt:null!=i.expires_in?new Date(Date.now()+1e3*i.expires_in):void 0,scopes:i.scope?.split(" ")??n.scopes,accountLabel:n.accountLabel,metadata:n.metadata};return await this.set(e,t,l),l}catch{return null}}}
+const DEFAULT_BUFFER_SECONDS = 300;
+function serializeCredential(credential) {
+    const serialized = {
+        accessToken: credential.accessToken,
+        scopes: credential.scopes
+    };
+    if (credential.refreshToken != null) {
+        serialized.refreshToken = credential.refreshToken;
+    }
+    if (credential.expiresAt != null) {
+        serialized.expiresAt = credential.expiresAt.toISOString();
+    }
+    if (credential.accountLabel != null) {
+        serialized.accountLabel = credential.accountLabel;
+    }
+    if (credential.metadata != null) {
+        serialized.metadata = credential.metadata;
+    }
+    return JSON.stringify(serialized);
+}
+function deserializeCredential(raw) {
+    // ParseJSONResultsPlugin may have already parsed the JSON string
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const credential = {
+        accessToken: parsed.accessToken,
+        scopes: parsed.scopes
+    };
+    if (parsed.refreshToken != null) {
+        credential.refreshToken = parsed.refreshToken;
+    }
+    if (parsed.expiresAt != null) {
+        credential.expiresAt = new Date(parsed.expiresAt);
+    }
+    if (parsed.accountLabel != null) {
+        credential.accountLabel = parsed.accountLabel;
+    }
+    if (parsed.metadata != null) {
+        credential.metadata = parsed.metadata;
+    }
+    return credential;
+}
+export class DBCredentialProvider {
+    #api;
+    #runtime;
+    #providers;
+    #bufferMs;
+    constructor(params){
+        this.#api = params.api;
+        this.#runtime = params.runtime;
+        this.#providers = params.providers;
+        this.#bufferMs = (params.bufferSeconds ?? DEFAULT_BUFFER_SECONDS) * 1000;
+    }
+    async get(providerName, ownerDID) {
+        const raw = await this.#api.getCredential(providerName, ownerDID);
+        if (raw == null) return null;
+        const credential = deserializeCredential(raw);
+        if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
+            const refreshed = await this.#refresh(providerName, ownerDID, credential, credential.refreshToken);
+            return refreshed ?? credential;
+        }
+        return credential;
+    }
+    async set(providerName, ownerDID, credential) {
+        await this.#api.setCredential(providerName, ownerDID, serializeCredential(credential));
+    }
+    async delete(providerName, ownerDID) {
+        await this.#api.deleteCredential(providerName, ownerDID);
+    }
+    #isExpiringSoon(credential) {
+        if (credential.expiresAt == null) return false;
+        return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
+    }
+    async #refresh(providerName, ownerDID, credential, refreshToken) {
+        const provider = this.#providers.find((p)=>p.name === providerName);
+        if (provider == null || provider.clientID == null || provider.clientSecret == null) {
+            return null;
+        }
+        try {
+            const response = await this.#runtime.fetch(provider.tokenEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                },
+                body: new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    refresh_token: refreshToken,
+                    client_id: provider.clientID,
+                    client_secret: provider.clientSecret
+                })
+            });
+            if (!response.ok) return null;
+            const tokenData = await response.json();
+            const refreshed = {
+                accessToken: tokenData.access_token,
+                refreshToken: tokenData.refresh_token ?? credential.refreshToken,
+                expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
+                scopes: tokenData.scope?.split(' ') ?? credential.scopes,
+                accountLabel: credential.accountLabel,
+                metadata: credential.metadata
+            };
+            await this.set(providerName, ownerDID, refreshed);
+            return refreshed;
+        } catch  {
+            return null;
+        }
+    }
+}

package/lib/index.d.ts

@@ -10,7 +10,7 @@ export type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, Connector
 export { createConnectorSchemaExtension, toConnectorSyncEventResult } from './schema.js';
 export { type RunSyncParams, SyncEngine, type SyncEngineParams } from './sync/engine.js';
 export { type OrchestrateSyncParams, type OrchestrateSyncResult, orchestrateSync, type SyncEventEmitter, } from './sync/orchestrate.js';
-export { EntityProcessor, type EntityProcessorParams, type ProcessBatchResult, } from './sync/processor.js';
+export { EntityProcessor, type EntityProcessorParams, type MutateDocuments, type ProcessBatchResult, type SignedDocumentWriter, } from './sync/processor.js';
 export { DBSyncStateStore } from './sync/state.js';
 export type { ConnectorAPI, SetSyncStateParams, SyncStateData };
 export { DBCredentialProvider, type DBCredentialProviderParams };
@@ -21,5 +21,7 @@ export type ConnectorPluginOptions = {
         boundary?: SyncBoundary;
         pollingInterval?: string;
     };
+    /** Override the sync-lease TTL in milliseconds (defaults to 5 minutes). */
+    syncLeaseTTL?: number;
 };
 export declare function createConnectorPlugin(options: ConnectorPluginOptions): (params: PluginFactoryParams) => KubunPlugin;