@kubun/plugin-connector 0.8.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/action.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialProvider, EntityRecord } from '@kubun/connector';
+import type { KubunDB, WritableDB } from '@kubun/db';
+import type { ConnectorRegistry } from './registry.js';
+export type ExecuteActionParams = {
+    connector: string;
+    action: string;
+    model: string;
+    input: Record<string, unknown>;
+    sourceID?: string;
+};
+export type ExecuteActionResult = {
+    entity: EntityRecord;
+    documentID: string | null;
+};
+export type ExecuteActionDeps = {
+    db: KubunDB | WritableDB;
+    registry: ConnectorRegistry;
+    credentialProvider: CredentialProvider;
+    ownerDID: string;
+};
+export declare function executeAction(params: ExecuteActionParams, deps: ExecuteActionDeps): Promise<ExecuteActionResult>;

package/lib/action.js

@@ -0,0 +1 @@
+import{DocumentID as e,DocumentModelID as r}from"@kubun/id";import{EntityProcessor as o}from"./sync/processor.js";export async function executeAction(t,n){let l,c,{db:i,registry:a,credentialProvider:u,ownerDID:s}=n,{connector:d,action:f,model:p,input:w,sourceID:m}=t,E=a.get(d);if(null==E)throw Error(`Connector "${d}" not found`);if(null==E.actionHandler)throw Error(`Connector "${d}" does not support actions`);if(null==E.actions?.find(e=>e.name===f))throw Error(`Action "${f}" not found on connector "${d}"`);let h=E.auth.provider,S=await u.get(h,s);if(null==S)throw Error(`No credential found for provider "${h}"`);let $=E.auth;if(null!=$.writeScopes&&!$.writeScopes.every(e=>S.scopes.includes(e))){let e=Error("INSUFFICIENT_SCOPES");throw e.code="INSUFFICIENT_SCOPES",e.requiredScopes=$.writeScopes,e}for(let e of Object.values(E.clusters)){for(let[r,o]of Object.entries(e.record))if(e.models[o].name===p){l=r;break}if(null!=l)break}if(null==l)throw Error(`Model "${p}" not found in connector "${d}" clusters`);let I=w;if("update"===f&&null!=m){let o=new TextEncoder().encode(`${d}:${m}`),t=e.create(r.fromString(l),s,o),n=await i.getDocument(t);n?.data!=null&&(I={...n.data,...w})}let b=E.actionHandler({credential:S});if("create"===f)c=await b.create(p,I);else if("update"===f){if(null==m)throw Error("sourceID is required for update actions");c=await b.update(p,m,I)}else throw Error(`Unsupported action: ${f}`);let C={};for(let e of Object.values(E.clusters))if(null!=e.record[l]){C=e.models[e.record[l]]?.fieldsMeta??{};break}let v=new o({db:i,modelID:l,ownerDID:s,connectorName:d,edgeFields:C,clusters:E.clusters}),N=await v.processBatch({entities:[c]});return{entity:c,documentID:N.documentIDs[0]??null}}

package/lib/api.d.ts

@@ -0,0 +1,29 @@
+import type { KubunDB } from '@kubun/db';
+export type SyncStateData = {
+    connectorName: string;
+    ownerDID: string;
+    checkpoint: string | null;
+    lastSyncedAt: string;
+    entityCount: number;
+    status: string;
+    error: string | null;
+};
+export type SetSyncStateParams = {
+    checkpoint?: string | null;
+    lastSyncedAt?: string;
+    entityCount?: number;
+    status: string;
+    error?: string | null;
+};
+export type ConnectorAPI = {
+    getSyncState: (connectorName: string, ownerDID: string) => Promise<SyncStateData | null>;
+    setSyncState: (connectorName: string, ownerDID: string, state: SetSyncStateParams) => Promise<SyncStateData>;
+    deleteSyncState: (connectorName: string, ownerDID: string) => Promise<void>;
+    listSyncStates: (connectorName: string) => Promise<Array<SyncStateData>>;
+    getCredential: (providerName: string, ownerDID: string) => Promise<string | null>;
+    setCredential: (providerName: string, ownerDID: string, credential: string) => Promise<void>;
+    deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
+};
+export declare function createConnectorAPI(params: {
+    db: KubunDB;
+}): ConnectorAPI;

package/lib/api.js

@@ -0,0 +1 @@
+function e(e){return{connectorName:e.connector_name,ownerDID:e.owner_did,checkpoint:e.checkpoint,lastSyncedAt:e.last_synced_at,entityCount:e.entity_count,status:e.status,error:e.error}}export function createConnectorAPI(t){return{async getSyncState(n,r){let a=await t.db.getDB(),c=await a.selectFrom("kubun_connector_sync_state").selectAll().where("connector_name","=",n).where("owner_did","=",r).executeTakeFirst();return null!=c?e(c):null},async setSyncState(n,r,a){let c=await t.db.getDB(),o=a.lastSyncedAt??new Date().toISOString(),s=a.entityCount??0,l=a.checkpoint??null,i=a.error??null;await c.insertInto("kubun_connector_sync_state").values({connector_name:n,owner_did:r,checkpoint:l,last_synced_at:o,entity_count:s,status:a.status,error:i}).onConflict(e=>e.columns(["connector_name","owner_did"]).doUpdateSet({checkpoint:l,last_synced_at:o,entity_count:s,status:a.status,error:i})).execute();let u=await c.selectFrom("kubun_connector_sync_state").selectAll().where("connector_name","=",n).where("owner_did","=",r).executeTakeFirst();if(null==u)throw Error("Failed to set sync state");return e(u)},async deleteSyncState(e,n){let r=await t.db.getDB();await r.deleteFrom("kubun_connector_sync_state").where("connector_name","=",e).where("owner_did","=",n).execute()},async listSyncStates(n){let r=await t.db.getDB();return(await r.selectFrom("kubun_connector_sync_state").selectAll().where("connector_name","=",n).execute()).map(e)},async getCredential(e,n){let r=await t.db.getDB(),a=await r.selectFrom("kubun_connector_credentials").selectAll().where("provider_name","=",e).where("owner_did","=",n).executeTakeFirst();return null!=a?a.credential:null},async setCredential(e,n,r){let a=await t.db.getDB();await a.insertInto("kubun_connector_credentials").values({provider_name:e,owner_did:n,credential:r}).onConflict(e=>e.columns(["provider_name","owner_did"]).doUpdateSet({credential:r})).execute()},async deleteCredential(e,n){let r=await t.db.getDB();await r.deleteFrom("kubun_connector_credentials").where("provider_name","=",e).where("owner_did","=",n).execute()}}}

package/lib/boundary.d.ts

@@ -0,0 +1,4 @@
+import type { SyncBoundary } from '@kubun/connector';
+export declare function parseDuration(duration: string): number | undefined;
+export declare function computeEffectiveBoundary(serverBoundary: SyncBoundary, userBoundary: SyncBoundary | undefined): SyncBoundary;
+export declare function isWithinBoundary(date: Date, boundary: SyncBoundary): boolean;

package/lib/boundary.js

@@ -0,0 +1 @@
+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}

package/lib/credential.d.ts

@@ -0,0 +1,16 @@
+import type { Runtime } from '@enkaku/runtime';
+import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
+import type { ConnectorAPI } from './api.js';
+export type DBCredentialProviderParams = {
+    api: ConnectorAPI;
+    runtime: Runtime;
+    providers: Array<OAuthProviderDefinition>;
+    bufferSeconds?: number;
+};
+export declare class DBCredentialProvider implements CredentialProvider {
+    #private;
+    constructor(params: DBCredentialProviderParams);
+    get(providerName: string, ownerDID: string): Promise<Credential | null>;
+    set(providerName: string, ownerDID: string, credential: Credential): Promise<void>;
+    delete(providerName: string, ownerDID: string): Promise<void>;
+}

package/lib/credential.js

@@ -0,0 +1 @@
+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}}}

package/lib/index.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectorDefinition, OAuthProviderDefinition, SyncBoundary } from '@kubun/connector';
+import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+import { type ConnectorAPI, type SetSyncStateParams, type SyncStateData } from './api.js';
+import { DBCredentialProvider, type DBCredentialProviderParams } from './credential.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';
+export { ConnectorRegistry } from './registry.js';
+export type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, ConnectorActionError, ConnectorActionInput, ConnectorActionResult, ConnectorExtensionConfig, ConnectorQueryContext, ConnectorState, ConnectorSyncEventResult, StartConnectorAuthInput, StartConnectorAuthOutput, SyncTriggerInput, SyncTriggerOutput, } from './schema.js';
+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 { DBSyncStateStore } from './sync/state.js';
+export type { ConnectorAPI, SetSyncStateParams, SyncStateData };
+export { DBCredentialProvider, type DBCredentialProviderParams };
+export type ConnectorPluginOptions = {
+    connectors: Array<ConnectorDefinition>;
+    providers?: Array<OAuthProviderDefinition>;
+    defaults?: {
+        boundary?: SyncBoundary;
+        pollingInterval?: string;
+    };
+};
+export declare function createConnectorPlugin(options: ConnectorPluginOptions): (params: PluginFactoryParams) => KubunPlugin;

package/lib/index.js

@@ -0,0 +1 @@
+import{fromEmitter as e}from"@enkaku/generator";import{executeAction as t}from"./action.js";import{createConnectorAPI as r}from"./api.js";import{DBCredentialProvider as n}from"./credential.js";import{ConnectorManager as o}from"./manager.js";import{createConnectorMigrations as c}from"./migration.js";import{OAuthService as s}from"./oauth.js";import{ConnectorRegistry as a}from"./registry.js";import{createConnectorSchemaExtension as i,toConnectorSyncEventResult as u}from"./schema.js";import{orchestrateSync as l}from"./sync/orchestrate.js";import{DBSyncStateStore as m}from"./sync/state.js";export{executeAction}from"./action.js";export{ConnectorManager}from"./manager.js";export{OAuthService}from"./oauth.js";export{ConnectorRegistry}from"./registry.js";export{createConnectorSchemaExtension,toConnectorSyncEventResult}from"./schema.js";export{SyncEngine}from"./sync/engine.js";export{orchestrateSync}from"./sync/orchestrate.js";export{EntityProcessor}from"./sync/processor.js";export{DBSyncStateStore}from"./sync/state.js";async function p(e,t,r,n,o){let c=t.get(o);if(null==c)throw Error(`Connector "${o}" not found`);let s=await e.getSyncState(o,n),a=!1,i=!1,u=null;if("device"!==c.auth.provider){let e=await r.get(c.auth.provider,n);if(null!=e){a=!0,null!=e.expiresAt&&(u=e.expiresAt.toISOString());let t=c.auth;i=null==t.writeScopes||t.writeScopes.every(t=>e.scopes.includes(t))}}return null==s?{name:o,status:"IDLE",authenticated:a,hasWriteAccess:i,authExpiresAt:u,lastSyncedAt:null,entityCount:null,error:null}:{name:o,status:"idle"===s.status?"IDLE":"syncing"===s.status?"SYNCING":"ERROR",authenticated:a,hasWriteAccess:i,authExpiresAt:u,lastSyncedAt:s.lastSyncedAt??null,entityCount:s.entityCount??null,error:s.error??null}}export function createConnectorPlugin(y){let f=y.providers??[];return d=>{let g=new a;for(let e of y.connectors)g.register(e);let S=r({db:d.db}),D=new n({api:S,runtime:d.runtime,providers:f}),h=new m({api:S}),w=new o({registry:g,logger:d.getLogger("connector"),defaults:y.defaults}),C=new s({runtime:d.runtime,providers:f,registry:g,credentialProvider:D}),j={types:d.db.adapter.types,functions:d.db.adapter.functions};return{name:"connector",migrations:{name:"connector",migrations:()=>c(j)},schemaExtension:e=>i({registry:g,config:e}),api:S,createContextFactory:()=>r=>({getConnectorState:e=>p(S,g,D,r.viewerDID,e),getConnectorStates:()=>Promise.all(g.list().map(e=>p(S,g,D,r.viewerDID,e))),startConnectorAuth:e=>C.startAuth(e),completeConnectorAuth:e=>C.completeAuth(e,r.viewerDID),triggerConnectorSync:async e=>{if(!g.has(e.connector))return{status:"ERROR",connectorName:e.connector};let t=await l({connectorName:e.connector,full:e.full??!1,registry:g,syncEventEmitter:w,stateStore:h,credentialProvider:D,ownerDID:r.viewerDID,db:d.db,boundary:y.defaults?.boundary});return{status:"started"===t.status?"STARTED":"already_syncing"===t.status?"ALREADY_SYNCING":"ERROR",connectorName:e.connector}},subscribeToConnectorSyncEvents:t=>{let r=null!=t?e=>e.connectorName===t:void 0,n=e(w.syncEvents,"sync",{filter:r});return async function*(){for await(let e of n)yield u(e)}()},executeConnectorAction:async e=>{try{let n=await t({connector:e.connector,action:e.action,model:e.model,input:e.input,sourceID:e.sourceID},{db:d.db,registry:g,credentialProvider:D,ownerDID:r.viewerDID});return{documentID:n.documentID,entity:n.entity,error:null}}catch(t){let e=t.code??"API_ERROR";return{documentID:null,entity:null,error:{code:e,message:t instanceof Error?t.message:String(t),requiredScopes:t.requiredScopes}}}}})}}}export{n as DBCredentialProvider};

package/lib/manager.d.ts

@@ -0,0 +1,45 @@
+import { EventEmitter } from '@enkaku/event';
+import type { ConnectorSyncEventPayload, SyncBoundary } from '@kubun/connector';
+import type { Logger } from '@kubun/logger';
+import type { ConnectorRegistry } from './registry.js';
+type SyncEvents = {
+    sync: ConnectorSyncEventPayload;
+};
+export type ConnectorActivatedEvent = {
+    connectorName: string;
+    graphID: string;
+};
+export type ConnectorDeactivatedEvent = {
+    connectorName: string;
+};
+export type ConnectorManagerEvents = {
+    'connector:activated': ConnectorActivatedEvent;
+    'connector:deactivated': ConnectorDeactivatedEvent;
+};
+export type ConnectorManagerParams = {
+    registry: ConnectorRegistry;
+    logger: Logger;
+    defaults?: {
+        boundary?: SyncBoundary;
+        pollingInterval?: string;
+    };
+};
+export declare class ConnectorManager {
+    #private;
+    constructor(params: ConnectorManagerParams);
+    get defaults(): {
+        boundary: SyncBoundary;
+        pollingInterval: string;
+    };
+    activateForGraph(graphID: string, connectorNames: Array<string>): void;
+    deactivateForGraph(graphID: string, connectorNames: Array<string>): void;
+    isActive(connectorName: string): boolean;
+    getActiveGraphs(connectorName: string): Array<string>;
+    listActive(): Array<string>;
+    onConnectorActivated(callback: (event: ConnectorActivatedEvent) => void): () => void;
+    onConnectorDeactivated(callback: (event: ConnectorDeactivatedEvent) => void): () => void;
+    get syncEvents(): EventEmitter<SyncEvents>;
+    emitSyncEvent(event: ConnectorSyncEventPayload): Promise<void>;
+    onSyncEvent(callback: (event: ConnectorSyncEventPayload) => void): () => void;
+}
+export {};

package/lib/manager.js

@@ -0,0 +1 @@
+import{EventEmitter as t}from"@enkaku/event";export class ConnectorManager{#t;#e;#n=new Map;#r=new t;#s=new t;#i;constructor(t){this.#t=t.registry,this.#e=t.logger,this.#i={boundary:t.defaults?.boundary??{maxAge:"P90D"},pollingInterval:t.defaults?.pollingInterval??"PT5M"}}get defaults(){return this.#i}activateForGraph(t,e){for(let n of e){if(!this.#t.has(n))throw Error(`Connector "${n}" is not registered`);let e=this.#n.get(n),r=null==e||0===e.size;null==e&&(e=new Set,this.#n.set(n,e)),e.add(t),r&&(this.#e.info("Connector {name} activated by graph {graphID}",{name:n,graphID:t}),this.#r.emit("connector:activated",{connectorName:n,graphID:t}))}}deactivateForGraph(t,e){for(let n of e){let e=this.#n.get(n);null!=e&&(e.delete(t),0===e.size&&(this.#n.delete(n),this.#e.info("Connector {name} deactivated",{name:n}),this.#r.emit("connector:deactivated",{connectorName:n})))}}isActive(t){let e=this.#n.get(t);return null!=e&&e.size>0}getActiveGraphs(t){let e=this.#n.get(t);return e?Array.from(e):[]}listActive(){return Array.from(this.#n.keys()).filter(t=>this.isActive(t))}onConnectorActivated(t){return this.#r.on("connector:activated",t)}onConnectorDeactivated(t){return this.#r.on("connector:deactivated",t)}get syncEvents(){return this.#s}async emitSyncEvent(t){await this.#s.emit("sync",t)}onSyncEvent(t){return this.#s.on("sync",t)}}

package/lib/migration.d.ts

@@ -0,0 +1,3 @@
+import type { PluginMigrationContext } from '@kubun/engine';
+import type { Migration } from 'kysely';
+export declare function createConnectorMigrations(ctx: PluginMigrationContext): Record<string, Migration>;

package/lib/migration.js

@@ -0,0 +1 @@
+export function createConnectorMigrations(t){let e=t.types;return{"001_create_connector_tables":{async up(t){await t.schema.createTable("kubun_connector_sync_state").ifNotExists().addColumn("connector_name",e.text,t=>t.notNull()).addColumn("owner_did",e.text,t=>t.notNull()).addColumn("checkpoint",e.text).addColumn("last_synced_at",e.text,t=>t.notNull()).addColumn("entity_count","integer",t=>t.notNull().defaultTo(0)).addColumn("status",e.text,t=>t.notNull()).addColumn("error",e.text).addPrimaryKeyConstraint("kubun_connector_sync_state_pkey",["connector_name","owner_did"]).execute(),await t.schema.createTable("kubun_connector_credentials").ifNotExists().addColumn("provider_name",e.text,t=>t.notNull()).addColumn("owner_did",e.text,t=>t.notNull()).addColumn("credential",e.text,t=>t.notNull()).addPrimaryKeyConstraint("kubun_connector_credentials_pkey",["provider_name","owner_did"]).execute()},async down(t){await t.schema.dropTable("kubun_connector_credentials").ifExists().execute(),await t.schema.dropTable("kubun_connector_sync_state").ifExists().execute()}}}}

package/lib/oauth.d.ts

@@ -0,0 +1,16 @@
+import type { Runtime } from '@enkaku/runtime';
+import type { CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
+import type { ConnectorRegistry } from './registry.js';
+import type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, StartConnectorAuthInput, StartConnectorAuthOutput } from './schema.js';
+export type OAuthServiceParams = {
+    runtime: Runtime;
+    providers: Array<OAuthProviderDefinition>;
+    registry: ConnectorRegistry;
+    credentialProvider: CredentialProvider;
+};
+export declare class OAuthService {
+    #private;
+    constructor(params: OAuthServiceParams);
+    startAuth(args: StartConnectorAuthInput): Promise<StartConnectorAuthOutput>;
+    completeAuth(args: CompleteConnectorAuthInput, viewerDID: string): Promise<CompleteConnectorAuthOutput>;
+}

package/lib/oauth.js

@@ -0,0 +1 @@
+export class OAuthService{#e;#r;#t;#i;constructor(e){this.#e=e.credentialProvider,this.#r=e.runtime,this.#t=e.providers,this.#i=e.registry}async startAuth(e){let r=this.#t.find(r=>r.name===e.provider);if(null==r)throw Error(`OAuth provider "${e.provider}" not found`);if(null==r.clientID)throw Error(`OAuth provider "${e.provider}" is missing clientID`);let t=!0===e.requestWriteAccess,i=new Set(r.baseScopes??[]);for(let r of e.connectors??this.#i.list()){let o=this.#i.get(r);if(null!=o&&o.auth.provider===e.provider){let e=o.auth;if(t&&null!=e.writeScopes)for(let r of e.writeScopes)i.add(r);else for(let r of e.scopes)i.add(r)}}let o=JSON.stringify({nonce:this.#r.getRandomID(),provider:e.provider}),s=new URL(r.authorizationEndpoint);return s.searchParams.set("client_id",r.clientID),s.searchParams.set("redirect_uri",e.redirectURL),s.searchParams.set("response_type","code"),s.searchParams.set("scope",Array.from(i).join(" ")),s.searchParams.set("state",o),s.searchParams.set("access_type","offline"),s.searchParams.set("prompt","consent"),{url:s.toString(),state:o}}async completeAuth(e,r){let t=this.#t.find(r=>r.name===e.provider);if(null==t)throw Error(`OAuth provider "${e.provider}" not found`);if(null==t.clientID||null==t.clientSecret)throw Error(`OAuth provider "${e.provider}" is missing clientID or clientSecret`);let i=await this.#r.fetch(t.tokenEndpoint,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"authorization_code",code:e.code,redirect_uri:e.redirectURL,client_id:t.clientID,client_secret:t.clientSecret})});if(!i.ok)throw Error(`Token exchange failed: ${i.statusText}`);let o=await i.json(),s=o.scope?.split(" ")??[];return await this.#e.set(e.provider,r,{accessToken:o.access_token,refreshToken:o.refresh_token,expiresAt:null!=o.expires_in?new Date(Date.now()+1e3*o.expires_in):void 0,scopes:s}),{providerName:e.provider,scopes:s}}}

package/lib/registry.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectorDefinition } from '@kubun/connector';
+export declare class ConnectorRegistry {
+    #private;
+    register(connector: ConnectorDefinition): void;
+    unregister(name: string): void;
+    get(name: string): ConnectorDefinition | undefined;
+    has(name: string): boolean;
+    list(): Array<string>;
+    getAll(): Array<ConnectorDefinition>;
+}

package/lib/registry.js

@@ -0,0 +1 @@
+export class ConnectorRegistry{#e=new Map;register(e){if(this.#e.has(e.name))throw Error(`Connector "${e.name}" is already registered`);this.#e.set(e.name,e)}unregister(e){this.#e.delete(e)}get(e){return this.#e.get(e)}has(e){return this.#e.has(e)}list(){return Array.from(this.#e.keys())}getAll(){return Array.from(this.#e.values())}}

package/lib/schema.d.ts

@@ -0,0 +1,111 @@
+import type { ConnectorSyncEventPayload } from '@kubun/connector';
+import type { SchemaExtension } from '@kubun/engine';
+import type { ConnectorRegistry } from './registry.js';
+/**
+ * Combined connector state returned by the `connector` and `connectors` queries.
+ * Mirrors `ConnectorSyncStateResult` from `@kubun/graphql/src/context.ts`.
+ */
+export type ConnectorState = {
+    name: string;
+    status: 'IDLE' | 'SYNCING' | 'ERROR';
+    authenticated: boolean;
+    hasWriteAccess: boolean;
+    authExpiresAt: string | null;
+    lastSyncedAt: string | null;
+    entityCount: number | null;
+    error: string | null;
+};
+/**
+ * Input/output types for connector auth mutations.
+ */
+export type StartConnectorAuthInput = {
+    provider: string;
+    redirectURL: string;
+    connectors?: Array<string> | null;
+    requestWriteAccess?: boolean | null;
+};
+export type StartConnectorAuthOutput = {
+    url: string;
+    state: string;
+};
+export type CompleteConnectorAuthInput = {
+    provider: string;
+    code: string;
+    redirectURL: string;
+    state?: string | null;
+};
+export type CompleteConnectorAuthOutput = {
+    providerName: string;
+    scopes: Array<string>;
+};
+export type SyncTriggerInput = {
+    connector: string;
+    full?: boolean | null;
+};
+export type SyncTriggerOutput = {
+    status: 'STARTED' | 'ALREADY_SYNCING' | 'ERROR';
+    connectorName: string;
+};
+/**
+ * Input for executing a connector action (create/update).
+ */
+export type ConnectorActionInput = {
+    connector: string;
+    action: 'create' | 'update';
+    model: string;
+    input: Record<string, unknown>;
+    sourceID?: string;
+};
+/**
+ * Structured error returned when a connector action fails.
+ */
+export type ConnectorActionError = {
+    code: string;
+    message: string;
+    requiredScopes?: Array<string>;
+};
+/**
+ * Result of executing a connector action.
+ */
+export type ConnectorActionResult = {
+    documentID: string | null;
+    entity: Record<string, unknown> | null;
+    error: ConnectorActionError | null;
+};
+/**
+ * Connector sync event payload for subscriptions (GraphQL result type).
+ */
+export type ConnectorSyncEventResult = {
+    type: 'STARTED' | 'PROGRESS' | 'COMPLETED' | 'ERROR';
+    connectorName: string;
+    entitiesProcessed: number | null;
+    entitiesFailed: number | null;
+    totalProcessed: number | null;
+    totalFailed: number | null;
+    duration: number | null;
+    error: string | null;
+};
+/**
+ * Transform a raw `ConnectorSyncEventPayload` into the GraphQL result shape.
+ */
+export declare function toConnectorSyncEventResult(event: ConnectorSyncEventPayload): ConnectorSyncEventResult;
+/**
+ * Per-request context methods for the Connector query and mutation fields.
+ * Provided by the context factory when registry + credentials are configured.
+ */
+export type ConnectorQueryContext = {
+    getConnectorState: (name: string) => Promise<ConnectorState>;
+    getConnectorStates: () => Promise<Array<ConnectorState>>;
+    startConnectorAuth: (args: StartConnectorAuthInput) => Promise<StartConnectorAuthOutput>;
+    completeConnectorAuth: (args: CompleteConnectorAuthInput) => Promise<CompleteConnectorAuthOutput>;
+    triggerConnectorSync: (args: SyncTriggerInput) => Promise<SyncTriggerOutput>;
+    subscribeToConnectorSyncEvents: (connector?: string | null) => AsyncIterable<ConnectorSyncEventResult>;
+    executeConnectorAction?: (args: ConnectorActionInput) => Promise<ConnectorActionResult>;
+};
+export type ConnectorExtensionConfig = {
+    connectors?: Array<string>;
+};
+export declare function createConnectorSchemaExtension(params: {
+    registry?: ConnectorRegistry;
+    config: ConnectorExtensionConfig;
+}): SchemaExtension;

package/lib/schema.js

@@ -0,0 +1,96 @@
+import{PluginNodeID as t}from"@kubun/id";export function toConnectorSyncEventResult(t){return{type:"started"===t.type?"STARTED":"progress"===t.type?"PROGRESS":"completed"===t.type?"COMPLETED":"ERROR",connectorName:t.connectorName,entitiesProcessed:t.entitiesProcessed??null,entitiesFailed:t.entitiesFailed??null,totalProcessed:t.totalProcessed??null,totalFailed:t.totalFailed??null,duration:t.duration??null,error:t.error??null}}function e(t){let e=[];for(let n of Object.values(t.clusters))for(let t of Object.values(n.record)){let o=n.models[t];o?.name==null||e.includes(o.name)||e.push(o.name)}return e}export function createConnectorSchemaExtension(n){let o=n.registry,r=[];r.push(`
+enum ConnectorSyncStatus {
+  IDLE
+  SYNCING
+  ERROR
+}
+
+enum SyncTriggerStatus {
+  STARTED
+  ALREADY_SYNCING
+  ERROR
+}
+
+enum ConnectorSyncEventType {
+  STARTED
+  PROGRESS
+  COMPLETED
+  ERROR
+}
+
+type Connector implements Node {
+  id: ID!
+  name: String!
+  status: ConnectorSyncStatus!
+  authenticated: Boolean!
+  hasWriteAccess: Boolean!
+  authExpiresAt: String
+  lastSyncedAt: String
+  entityCount: Int
+  error: String
+}
+
+type StartConnectorAuthResult {
+  url: String!
+  state: String!
+}
+
+type CompleteConnectorAuthResult {
+  providerName: String!
+  scopes: [String!]!
+}
+
+type SyncTriggerResult {
+  status: SyncTriggerStatus!
+  connectorName: String!
+}
+
+type ConnectorSyncEvent {
+  type: ConnectorSyncEventType!
+  connectorName: String!
+  entitiesProcessed: Int
+  entitiesFailed: Int
+  totalProcessed: Int
+  totalFailed: Int
+  duration: Float
+  error: String
+}
+
+type ConnectorActionError {
+  code: String!
+  message: String!
+  requiredScopes: [String!]
+}
+
+extend type Query {
+  connector(name: String!): Connector!
+  connectors: [Connector!]!
+}
+
+extend type Mutation {
+  startConnectorAuth(provider: String!, redirectURL: String!, connectors: [String!], requestWriteAccess: Boolean): StartConnectorAuthResult!
+  completeConnectorAuth(provider: String!, code: String!, redirectURL: String!, state: String): CompleteConnectorAuthResult!
+  syncConnector(connector: String!, full: Boolean): SyncTriggerResult!
+}
+
+extend type Subscription {
+  connectorSyncEvents(connector: String): ConnectorSyncEvent!
+}
+`);let c=[];if(null!=o){let t=new Set;for(let n of o.getAll()){if(null==n.actions||0===n.actions.length)continue;let o=n.actions.some(t=>"create"===t.name),i=n.actions.some(t=>"update"===t.name);if(o||i)for(let s of e(n).filter(t=>"ExternalEntity"!==t))t.has(s)||(t.add(s),r.push(`
+type Connector${s}Payload {
+  documentID: String
+  entity: JSON
+  error: ConnectorActionError
+}
+`)),o&&(r.push(`
+input ConnectorCreate${s}Input {
+  input: JSON!
+}
+`),c.push(`  connectorCreate${s}(input: ConnectorCreate${s}Input!): Connector${s}Payload!`)),i&&(r.push(`
+input ConnectorUpdate${s}Input {
+  sourceID: String!
+  input: JSON!
+}
+`),c.push(`  connectorUpdate${s}(input: ConnectorUpdate${s}Input!): Connector${s}Payload!`))}}c.length>0&&r.push(`extend type Mutation {
+${c.join("\n")}
+}`);let i=r.join("\n"),s={startConnectorAuth:(t,e,n)=>n.startConnectorAuth(e),completeConnectorAuth:(t,e,n)=>n.completeConnectorAuth(e),syncConnector:(t,e,n)=>n.triggerConnectorSync(e)};if(null!=o)for(let t of o.getAll()){if(null==t.actions||0===t.actions.length)continue;let n=t.actions.some(t=>"create"===t.name),o=t.actions.some(t=>"update"===t.name);if(n||o)for(let r of e(t).filter(t=>"ExternalEntity"!==t)){if(n){let e=t.name;s[`connectorCreate${r}`]=async(t,n,o)=>{if(null==o.executeConnectorAction)throw Error("executeConnectorAction is not available in this context");let c=n.input;return await o.executeConnectorAction({connector:e,action:"create",model:r,input:c.input})}}if(o){let e=t.name;s[`connectorUpdate${r}`]=async(t,n,o)=>{if(null==o.executeConnectorAction)throw Error("executeConnectorAction is not available in this context");let c=n.input;return await o.executeConnectorAction({connector:e,action:"update",model:r,input:c.input,sourceID:c.sourceID})}}}}return{sdl:i,resolvers:{queryFields:{connector:(t,e,n)=>n.getConnectorState(e.name),connectors:(t,e,n)=>n.getConnectorStates()},mutationFields:s,subscriptionFields:{connectorSyncEvents:{resolve:t=>t,subscribe:(t,e,n)=>n.subscribeToConnectorSyncEvents(e.connector)}},typeFields:{Connector:{id:e=>t.create("connector","Connector",e.name).toString()}},nodeResolvers:{Connector:{resolve:(t,e)=>e.getConnectorState(t)}}}}}

package/lib/sync/engine.d.ts

@@ -0,0 +1,22 @@
+import type { DataProvider, SyncBoundary, SyncEvent, SyncStateStore } from '@kubun/connector';
+import type { KubunDB } from '@kubun/db';
+import type { ClustersRecord } from '@kubun/protocol';
+export type SyncEngineParams = {
+    db: KubunDB;
+    stateStore: SyncStateStore;
+    connectorName: string;
+    clusters: ClustersRecord;
+};
+export type RunSyncParams = {
+    provider: DataProvider;
+    ownerDID: string;
+    boundary: SyncBoundary;
+    full?: boolean;
+    signal?: AbortSignal;
+};
+export declare class SyncEngine {
+    #private;
+    constructor(params: SyncEngineParams);
+    on(event: 'sync', callback: (event: SyncEvent) => void): () => void;
+    run(params: RunSyncParams): Promise<void>;
+}

package/lib/sync/engine.js

@@ -0,0 +1 @@
+import{EventEmitter as t}from"@enkaku/event";import{EntityProcessor as e}from"./processor.js";export class SyncEngine{#t;#e;#n;#s;#o;#c=new Map;#r=new t;constructor(t){for(let e of(this.#t=t.db,this.#e=t.stateStore,this.#n=t.connectorName,this.#s=t.clusters,this.#o=new Map,Object.values(t.clusters)))for(let[t,n]of Object.entries(e.record))this.#o.set(t,e.models[n])}on(t,e){return this.#r.on(t,e)}#i(t,n){let s=this.#c.get(t);if(null!=s)return s;let o=this.#o.get(t);if(null==o)throw Error(`Unknown model ID "${t}" in connector "${this.#n}"`);let c=new e({db:this.#t,modelID:t,ownerDID:n,connectorName:this.#n,edgeFields:o.fieldsMeta,clusters:this.#s});return this.#c.set(t,c),c}async run(t){let{provider:e,ownerDID:n,boundary:s,full:o,signal:c}=t,r=Date.now(),i=await this.#e.get(this.#n,n),a=!o&&i?.checkpoint!=null,l=a?"incremental":"initial";await this.#e.set(this.#n,n,{checkpoint:i?.checkpoint??null,lastSyncedAt:i?.lastSyncedAt??new Date().toISOString(),entityCount:i?.entityCount??0,status:"syncing"});let h=0,d=0,y=0,m=i?.checkpoint??null;try{let t={boundary:s,checkpoint:a?i?.checkpoint:void 0,signal:c};for await(let s of a?e.fetchChanges({...t,lastSyncedAt:i?.lastSyncedAt?new Date(i.lastSyncedAt):void 0}):e.fetchAll(t)){y++;let t=this.#i(s.modelID,n),e=await t.processBatch(s);h+=e.created+e.updated+e.deleted,d+=e.failed,null!=s.checkpoint&&(m=s.checkpoint);let o={type:"sync:progress",connectorName:this.#n,phase:l,entitiesProcessed:h,entitiesFailed:d,currentBatch:y,checkpoint:m};await this.#r.emit("sync",o),await this.#e.set(this.#n,n,{checkpoint:m,lastSyncedAt:new Date().toISOString(),entityCount:(i?.entityCount??0)+h,status:"syncing"})}let o=Date.now()-r;await this.#e.set(this.#n,n,{checkpoint:m,lastSyncedAt:new Date().toISOString(),entityCount:(i?.entityCount??0)+h,status:"idle"});let u={type:"sync:complete",connectorName:this.#n,totalProcessed:h,totalFailed:d,duration:o};await this.#r.emit("sync",u)}catch(s){let t=s instanceof Error?s.message:String(s);await this.#e.set(this.#n,n,{checkpoint:m,lastSyncedAt:i?.lastSyncedAt??new Date().toISOString(),entityCount:i?.entityCount??0,status:"error",error:t});let e={type:"sync:error",connectorName:this.#n,error:t};await this.#r.emit("sync",e)}}}

package/lib/sync/orchestrate.d.ts

@@ -0,0 +1,26 @@
+import type { ConnectorSyncEventPayload, CredentialProvider, SyncBoundary, SyncStateStore } from '@kubun/connector';
+import type { KubunDB } from '@kubun/db';
+import type { ConnectorRegistry } from '../registry.js';
+/**
+ * Minimal interface for the sync event emitter dependency.
+ * ConnectorManager (not yet ported) satisfies this — when it is ported,
+ * this type can be replaced with the concrete class.
+ */
+export type SyncEventEmitter = {
+    emitSyncEvent(event: ConnectorSyncEventPayload): Promise<void>;
+};
+export type OrchestrateSyncParams = {
+    connectorName: string;
+    full: boolean;
+    registry: ConnectorRegistry;
+    syncEventEmitter: SyncEventEmitter;
+    stateStore: SyncStateStore;
+    credentialProvider: CredentialProvider;
+    ownerDID: string;
+    db: KubunDB;
+    boundary?: SyncBoundary;
+};
+export type OrchestrateSyncResult = {
+    status: 'started' | 'already_syncing' | 'error';
+};
+export declare function orchestrateSync(params: OrchestrateSyncParams): Promise<OrchestrateSyncResult>;

package/lib/sync/orchestrate.js

@@ -0,0 +1 @@
+import{SyncEngine as e}from"./engine.js";export async function orchestrateSync(t){let{connectorName:r,full:n,registry:s,syncEventEmitter:a,stateStore:i,credentialProvider:o,ownerDID:c,db:l}=t,u=s.get(r);if(null==u)return{status:"error"};let y=await i.get(r,c);if(y?.status==="syncing")return{status:"already_syncing"};let d="device"!==u.auth.provider?u.auth.provider:null,p=d?await o.get(d,c):null;if(null!=d&&null==p||null==u.serverProvider)return{status:"error"};let v=t.boundary??{maxAge:"P90D"},g=u.serverProvider({credential:p??{accessToken:"",scopes:[]},boundary:v}),m=new e({db:l,stateStore:i,connectorName:r,clusters:u.clusters});return await a.emitSyncEvent({type:"started",connectorName:r}),m.on("sync",e=>{"sync:progress"===e.type?a.emitSyncEvent({type:"progress",connectorName:r,entitiesProcessed:e.entitiesProcessed,entitiesFailed:e.entitiesFailed}):"sync:complete"===e.type?a.emitSyncEvent({type:"completed",connectorName:r,totalProcessed:e.totalProcessed,totalFailed:e.totalFailed,duration:e.duration}):"sync:error"===e.type&&a.emitSyncEvent({type:"error",connectorName:r,error:e.error})}),m.run({provider:g,ownerDID:c,boundary:v,full:n}).catch(async e=>{await a.emitSyncEvent({type:"error",connectorName:r,error:e instanceof Error?e.message:String(e)})}),{status:"started"}}

package/lib/sync/processor.d.ts

@@ -0,0 +1,23 @@
+import type { EntityBatch } from '@kubun/connector';
+import type { KubunDB, WritableDB } from '@kubun/db';
+import type { ClustersRecord, DocumentFieldsMeta } from '@kubun/protocol';
+export type ProcessBatchResult = {
+    created: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    documentIDs: Array<string>;
+};
+export type EntityProcessorParams = {
+    db: KubunDB | WritableDB;
+    modelID: string;
+    ownerDID: string;
+    connectorName: string;
+    edgeFields?: DocumentFieldsMeta;
+    clusters?: ClustersRecord;
+};
+export declare class EntityProcessor {
+    #private;
+    constructor(params: EntityProcessorParams);
+    processBatch(batch: Pick<EntityBatch, 'entities' | 'deleted'>): Promise<ProcessBatchResult>;
+}

package/lib/sync/processor.js

@@ -0,0 +1 @@
+import{DocumentID as e,DocumentModelID as t}from"@kubun/id";export class EntityProcessor{#e;#t;#r;#o;#c;#n;constructor(e){this.#e=e.db,this.#t=t.fromString(e.modelID),this.#r=e.ownerDID,this.#o=e.connectorName,this.#c=e.edgeFields??{},this.#n=e.clusters}#s(t,r){let o=new TextEncoder().encode(`${t}:${r}`);return e.create(this.#t,this.#r,o)}#i(e){let r,o=this.#n;if(null==o)return;for(let t of Object.values(o))if(null!=t.record[e])return e;try{r=t.fromString(e)}catch{return}if(!r.isLocal)return;let c=r.index;for(let e of Object.values(o))for(let[t,r]of Object.entries(e.record))if(r===c)return t}#l(r){if(null==this.#n||0===Object.keys(this.#c).length)return r;let o={...r};for(let[c,n]of Object.entries(this.#c)){if("document"!==n.type||null==n.model)continue;let s=r[c];if(null==s||"object"!=typeof s)continue;let i=s.sourceService,l=s.sourceID;if("string"!=typeof i||"string"!=typeof l)continue;let u=this.#i(n.model);if(null==u)continue;let d=new TextEncoder().encode(`${i}:${l}`),D=e.create(t.fromString(u),this.#r,d);o[c]=D.toString()}return o}async processBatch(e){let t=0,r=0,o=0,c=0,n=[];for(let o of e.entities)try{let e=this.#s(o.sourceService,o.sourceID),c=await this.#e.getDocument(e),s={...o,lastSyncedAt:new Date().toISOString()},i=this.#l(s);if(null==c){let r=new TextEncoder().encode(`${o.sourceService}:${o.sourceID}`);await this.#e.createDocument({id:e,owner:this.#r,unique:r,data:i}),t++}else await this.#e.saveDocument({id:e,existing:c,data:i}),r++;n.push(e.toString())}catch{c++}if(e.deleted)for(let t of e.deleted)try{let e=this.#s(t.sourceService,t.sourceID),r=await this.#e.getDocument(e);null!=r&&(await this.#e.saveDocument({id:e,existing:r,data:{sourceService:t.sourceService,sourceID:t.sourceID,lastSyncedAt:new Date().toISOString(),_deleted:!0}}),o++)}catch{c++}return{created:t,updated:r,deleted:o,failed:c,documentIDs:n}}}

package/lib/sync/state.d.ts

@@ -0,0 +1,17 @@
+import type { SyncState, SyncStateEntry, SyncStateStore } from '@kubun/connector';
+import type { ConnectorAPI } from '../api.js';
+/**
+ * DB-backed SyncStateStore that wraps ConnectorAPI methods.
+ * Maps between the SyncState type (with unknown checkpoint) and the
+ * SyncStateData type (with JSON-serialized string checkpoint).
+ */
+export declare class DBSyncStateStore implements SyncStateStore {
+    #private;
+    constructor(params: {
+        api: ConnectorAPI;
+    });
+    get(connectorName: string, ownerDID: string): Promise<SyncState | null>;
+    set(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
+    delete(connectorName: string, ownerDID: string): Promise<void>;
+    listForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
+}

package/lib/sync/state.js

@@ -0,0 +1 @@
+export class DBSyncStateStore{#t;constructor(t){this.#t=t.api}async get(t,n){let e=await this.#t.getSyncState(t,n);return null==e?null:{checkpoint:null!=e.checkpoint?"string"==typeof e.checkpoint?JSON.parse(e.checkpoint):e.checkpoint:null,lastSyncedAt:e.lastSyncedAt,entityCount:e.entityCount,status:e.status,error:e.error??void 0}}async set(t,n,e){await this.#t.setSyncState(t,n,{checkpoint:null!=e.checkpoint?JSON.stringify(e.checkpoint):null,lastSyncedAt:e.lastSyncedAt,entityCount:e.entityCount,status:e.status,error:e.error??null})}async delete(t,n){await this.#t.deleteSyncState(t,n)}async listForConnector(t){return(await this.#t.listSyncStates(t)).map(t=>({connectorName:t.connectorName,ownerDID:t.ownerDID,checkpoint:null!=t.checkpoint?"string"==typeof t.checkpoint?JSON.parse(t.checkpoint):t.checkpoint:null,lastSyncedAt:t.lastSyncedAt,entityCount:t.entityCount,status:t.status,error:t.error??void 0}))}}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kubun/plugin-connector",
+  "version": "0.8.0",
+  "license": "see LICENSE.md",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@enkaku/async": "^0.14.0",
+    "@enkaku/event": "^0.14.1",
+    "@enkaku/generator": "^0.14.0",
+    "@enkaku/runtime": "^0.14.0",
+    "graphql": "^16.13.2",
+    "graphql-scalars": "^1.25.0",
+    "kysely": "^0.28.16",
+    "@kubun/connector": "^0.8.0",
+    "@kubun/db": "^0.8.0",
+    "@kubun/engine": "^0.8.0",
+    "@kubun/graphql": "^0.8.0",
+    "@kubun/id": "^0.8.0",
+    "@kubun/logger": "^0.8.0",
+    "@kubun/protocol": "^0.8.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^11.14.0",
+    "get-port": "^7.2.0",
+    "@kubun/db-postgres": "^0.8.0",
+    "@kubun/test-utils": "^0.8.0"
+  },
+  "scripts": {
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}