@kubun/connector 0.5.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/index.d.ts

@@ -0,0 +1,8 @@
+export { type ConnectorActivatedEvent, type ConnectorDeactivatedEvent, ConnectorManager, type ConnectorManagerEvents, type ConnectorManagerParams, } from './manager.js';
+export { externalEntityDefinition } from './models/external-entity.js';
+export { createOAuthRoutes, type OAuthRoutesParams, type StateStore } from './oauth/routes.js';
+export type { Credential, CredentialProvider, OAuthProviderDefinition, OAuthState, TokenResponse, } from './oauth/types.js';
+export { type ConnectorActionParams, type ConnectorActionResult, type ConnectorAuthCompleteParams, type ConnectorAuthCompleteResult, type ConnectorAuthURLParams, type ConnectorAuthURLResult, type ConnectorProtocol, type ConnectorPushCompleteParams, type ConnectorPushCompleteResult, type ConnectorPushParams, type ConnectorPushResult, type ConnectorStatusParams, type ConnectorStatusResult, type ConnectorSyncParams, type ConnectorSyncReceive, type ConnectorSyncResult, connectorProtocol, } from './protocol.js';
+export { ConnectorRegistry } from './registry.js';
+export { computeEffectiveBoundary, isWithinBoundary, parseDuration, } from './sync/boundary.js';
+export type { ActionDefinition, ActionResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, DataProvider, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchParams, OAuthConnectorAuth, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncProgressEvent, UserSyncPreferences, WebhookParams, WebhookRegistration, } from './types.js';

package/lib/index.js

@@ -0,0 +1 @@
+export{ConnectorManager}from"./manager.js";export{externalEntityDefinition}from"./models/external-entity.js";export{createOAuthRoutes}from"./oauth/routes.js";export{connectorProtocol}from"./protocol.js";export{ConnectorRegistry}from"./registry.js";export{computeEffectiveBoundary,isWithinBoundary,parseDuration}from"./sync/boundary.js";

package/lib/manager.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from '@kubun/logger';
+import type { ConnectorRegistry } from './registry.js';
+import type { SyncBoundary } from './types.js';
+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;
+}

package/lib/manager.js

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

package/lib/models/external-entity.d.ts

@@ -0,0 +1,11 @@
+import type { DocumentModelInput } from '@kubun/protocol';
+/**
+ * ExternalEntity is the base interface for documents synced from external services.
+ *
+ * Fields:
+ * - sourceService: External service identifier (e.g., "jira", "slack", "ios-contacts")
+ * - sourceID: External entity native ID
+ * - sourceURL: Optional URL back to the entity in the source service
+ * - lastSyncedAt: Timestamp of when this entity was last synced
+ */
+export declare const externalEntityDefinition: DocumentModelInput;

package/lib/models/external-entity.js

@@ -0,0 +1 @@
+import{dateTimeSchema as e,urlSchema as i}from"@kubun/scalars";export const externalEntityDefinition={name:"ExternalEntity",behavior:"interface",schema:{type:"object",properties:{sourceService:{$ref:"#/definitions/SourceService"},sourceID:{$ref:"#/definitions/SourceID"},sourceURL:{$ref:"#/definitions/SourceURL"},lastSyncedAt:{$ref:"#/definitions/DateTime"}},required:["sourceService","sourceID","lastSyncedAt"],additionalProperties:!0,definitions:{SourceService:{type:"string",title:"SourceService",minLength:1,maxLength:50},SourceID:{type:"string",title:"SourceID",minLength:1,maxLength:500},SourceURL:i,DateTime:e}},fieldsMeta:{}};

package/lib/oauth/routes.d.ts

@@ -0,0 +1,19 @@
+import { Hono } from 'hono';
+import type { Credential, OAuthProviderDefinition, OAuthState } from './types.js';
+export type StateStore = {
+    set(nonce: string, state: OAuthState): Promise<void> | void;
+    get(nonce: string): Promise<OAuthState | null> | OAuthState | null;
+    delete(nonce: string): Promise<void> | void;
+};
+export type OAuthRoutesParams = {
+    providers: Array<OAuthProviderDefinition>;
+    stateStore: StateStore;
+    /** Maximum age of OAuth state in milliseconds (default: 10 minutes) */
+    stateTTL?: number;
+    onTokenReceived?: (params: {
+        provider: OAuthProviderDefinition;
+        state: OAuthState;
+        credential: Credential;
+    }) => Promise<void> | void;
+};
+export declare function createOAuthRoutes(params: OAuthRoutesParams): Hono;

package/lib/oauth/routes.js

@@ -0,0 +1 @@
+import{Hono as e}from"hono";export function createOAuthRoutes(r){let{providers:t,stateStore:a,stateTTL:i=6e5,onTokenReceived:o}=r,n=new Map(t.map(e=>[e.name,e])),s=new e;return s.get("/auth/:provider/start",async e=>{let r,t=e.req.param("provider"),i=n.get(t);if(!i)return e.json({error:`Unknown provider: ${t}`},404);if(!i.clientID)return e.json({error:`Provider ${t} is not configured with a clientID`},500);let o=e.req.query("redirect_uri");if(!o)return e.json({error:"redirect_uri is required"},400);let s=e.req.query("scope"),c=s?s.split(","):[],d=[...i.baseScopes??[],...c],p=(r=new Uint8Array(32),crypto.getRandomValues(r),Array.from(r,e=>e.toString(16).padStart(2,"0")).join("")),u={provider:t,redirectURL:o,nonce:p,createdAt:Date.now()};await a.set(p,u);let l=new URL(i.authorizationEndpoint);return l.searchParams.set("client_id",i.clientID),l.searchParams.set("redirect_uri",o),l.searchParams.set("response_type","code"),l.searchParams.set("state",p),d.length>0&&l.searchParams.set("scope",d.join(" ")),e.redirect(l.toString())}),s.get("/auth/:provider/callback",async e=>{let r=e.req.param("provider"),t=n.get(r);if(!t)return e.json({error:`Unknown provider: ${r}`},404);let s=e.req.query("code"),c=e.req.query("state"),d=e.req.query("error");if(d){let r=e.req.query("error_description");return e.json({error:d,error_description:r},400)}if(!s||!c)return e.json({error:"Missing code or state"},400);let p=await a.get(c);if(!p)return e.json({error:"Invalid or expired state"},400);if(Date.now()-p.createdAt>i)return await a.delete(c),e.json({error:"State has expired"},400);if(p.provider!==r)return e.json({error:"State provider mismatch"},400);let u=await fetch(t.tokenEndpoint,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"authorization_code",code:s,redirect_uri:p.redirectURL,client_id:t.clientID??"",client_secret:t.clientSecret??""})});if(!u.ok){let r=await u.text();return e.json({error:"Token exchange failed",details:r},500)}let l=await u.json(),h={accessToken:l.access_token,refreshToken:l.refresh_token,expiresAt:l.expires_in?new Date(Date.now()+1e3*l.expires_in):void 0,scopes:l.scope?l.scope.split(" "):[]};await a.delete(c),o&&await o({provider:t,state:p,credential:h});let w=new URL(p.redirectURL);return w.searchParams.set("oauth_status","success"),w.searchParams.set("provider",r),e.redirect(w.toString())}),s}

package/lib/oauth/types.d.ts

@@ -0,0 +1,35 @@
+export type OAuthProviderDefinition = {
+    name: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    baseScopes?: Array<string>;
+    clientID?: string;
+    clientSecret?: string;
+};
+export type Credential = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: Date;
+    scopes: Array<string>;
+    accountLabel?: string;
+    metadata?: Record<string, unknown>;
+};
+export type CredentialProvider = {
+    get(providerName: string, ownerDID: string): Promise<Credential | null>;
+    set(providerName: string, ownerDID: string, credential: Credential): Promise<void>;
+    delete(providerName: string, ownerDID: string): Promise<void>;
+};
+export type OAuthState = {
+    provider: string;
+    redirectURL: string;
+    connectors?: Array<string>;
+    nonce: string;
+    createdAt: number;
+};
+export type TokenResponse = {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type: string;
+    scope?: string;
+};

package/lib/oauth/types.js

@@ -0,0 +1 @@
+export{};

package/lib/protocol.d.ts

@@ -0,0 +1,337 @@
+import type { FromSchema } from '@enkaku/schema';
+export declare const connectorProtocol: {
+    readonly 'connector/sync': {
+        readonly type: "stream";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connector: {
+                    readonly type: "string";
+                    readonly description: "Connector name";
+                };
+                readonly full: {
+                    readonly type: "boolean";
+                    readonly description: "Force full sync instead of incremental";
+                };
+            };
+            readonly required: readonly ["connector"];
+            readonly additionalProperties: false;
+        };
+        readonly receive: {
+            readonly type: "object";
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["progress", "entity", "error"];
+                };
+                readonly connectorName: {
+                    readonly type: "string";
+                };
+                readonly phase: {
+                    readonly type: "string";
+                    readonly enum: readonly ["initial", "incremental"];
+                };
+                readonly entitiesProcessed: {
+                    readonly type: "number";
+                };
+                readonly entitiesFailed: {
+                    readonly type: "number";
+                };
+                readonly currentBatch: {
+                    readonly type: "number";
+                };
+                readonly checkpoint: {};
+                readonly entity: {
+                    readonly type: "object";
+                };
+                readonly documentID: {
+                    readonly type: "string";
+                };
+                readonly error: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly success: {
+                    readonly type: "boolean";
+                };
+                readonly totalProcessed: {
+                    readonly type: "number";
+                };
+                readonly totalFailed: {
+                    readonly type: "number";
+                };
+                readonly duration: {
+                    readonly type: "number";
+                };
+            };
+            readonly required: readonly ["success", "totalProcessed", "totalFailed", "duration"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/status': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connector: {
+                    readonly type: "string";
+                    readonly description: "Optional connector name to filter";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connectors: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly lastSyncedAt: {
+                                readonly type: "string";
+                            };
+                            readonly entityCount: {
+                                readonly type: "number";
+                            };
+                            readonly status: {
+                                readonly type: "string";
+                                readonly enum: readonly ["active", "inactive", "syncing", "error"];
+                            };
+                            readonly error: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["name", "status"];
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly required: readonly ["connectors"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/action': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connector: {
+                    readonly type: "string";
+                };
+                readonly action: {
+                    readonly type: "string";
+                };
+                readonly input: {
+                    readonly type: "object";
+                };
+            };
+            readonly required: readonly ["connector", "action", "input"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly raw: {
+                    readonly type: "object";
+                };
+                readonly entity: {
+                    readonly type: "object";
+                };
+                readonly documentID: {
+                    readonly type: "string";
+                };
+                readonly deletedDocumentID: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/push': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connector: {
+                    readonly type: "string";
+                };
+                readonly batch: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly entities: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                            };
+                        };
+                        readonly deleted: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly sourceService: {
+                                        readonly type: "string";
+                                    };
+                                    readonly sourceID: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["sourceService", "sourceID"];
+                            };
+                        };
+                        readonly checkpoint: {};
+                        readonly hasMore: {
+                            readonly type: "boolean";
+                        };
+                    };
+                    readonly required: readonly ["entities", "hasMore"];
+                    readonly additionalProperties: false;
+                };
+                readonly checkpoint: {};
+            };
+            readonly required: readonly ["connector", "batch"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly processed: {
+                    readonly type: "number";
+                };
+                readonly failed: {
+                    readonly type: "number";
+                };
+                readonly documentIDs: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly required: readonly ["processed", "failed", "documentIDs"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/push-complete': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connector: {
+                    readonly type: "string";
+                };
+                readonly checkpoint: {};
+            };
+            readonly required: readonly ["connector", "checkpoint"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly acknowledged: {
+                    readonly type: "boolean";
+                };
+            };
+            readonly required: readonly ["acknowledged"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/auth-url': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                };
+                readonly redirectURL: {
+                    readonly type: "string";
+                };
+                readonly connectors: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly required: readonly ["provider", "redirectURL"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly url: {
+                    readonly type: "string";
+                };
+                readonly state: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["url", "state"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'connector/auth-complete': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                };
+                readonly code: {
+                    readonly type: "string";
+                };
+                readonly state: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["provider", "code", "state"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly providerName: {
+                    readonly type: "string";
+                };
+                readonly accountLabel: {
+                    readonly type: "string";
+                };
+                readonly scopes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly required: readonly ["providerName", "scopes"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export type ConnectorProtocol = typeof connectorProtocol;
+export type ConnectorSyncParams = FromSchema<ConnectorProtocol['connector/sync']['param']>;
+export type ConnectorSyncReceive = FromSchema<ConnectorProtocol['connector/sync']['receive']>;
+export type ConnectorSyncResult = FromSchema<ConnectorProtocol['connector/sync']['result']>;
+export type ConnectorStatusParams = FromSchema<ConnectorProtocol['connector/status']['param']>;
+export type ConnectorStatusResult = FromSchema<ConnectorProtocol['connector/status']['result']>;
+export type ConnectorActionParams = FromSchema<ConnectorProtocol['connector/action']['param']>;
+export type ConnectorActionResult = FromSchema<ConnectorProtocol['connector/action']['result']>;
+export type ConnectorPushParams = FromSchema<ConnectorProtocol['connector/push']['param']>;
+export type ConnectorPushResult = FromSchema<ConnectorProtocol['connector/push']['result']>;
+export type ConnectorPushCompleteParams = FromSchema<ConnectorProtocol['connector/push-complete']['param']>;
+export type ConnectorPushCompleteResult = FromSchema<ConnectorProtocol['connector/push-complete']['result']>;
+export type ConnectorAuthURLParams = FromSchema<ConnectorProtocol['connector/auth-url']['param']>;
+export type ConnectorAuthURLResult = FromSchema<ConnectorProtocol['connector/auth-url']['result']>;
+export type ConnectorAuthCompleteParams = FromSchema<ConnectorProtocol['connector/auth-complete']['param']>;
+export type ConnectorAuthCompleteResult = FromSchema<ConnectorProtocol['connector/auth-complete']['result']>;

package/lib/protocol.js

@@ -0,0 +1 @@
+export const connectorProtocol={"connector/sync":{type:"stream",param:{type:"object",properties:{connector:{type:"string",description:"Connector name"},full:{type:"boolean",description:"Force full sync instead of incremental"}},required:["connector"],additionalProperties:!1},receive:{type:"object",properties:{type:{type:"string",enum:["progress","entity","error"]},connectorName:{type:"string"},phase:{type:"string",enum:["initial","incremental"]},entitiesProcessed:{type:"number"},entitiesFailed:{type:"number"},currentBatch:{type:"number"},checkpoint:{},entity:{type:"object"},documentID:{type:"string"},error:{type:"string"}},additionalProperties:!1},result:{type:"object",properties:{success:{type:"boolean"},totalProcessed:{type:"number"},totalFailed:{type:"number"},duration:{type:"number"}},required:["success","totalProcessed","totalFailed","duration"],additionalProperties:!1}},"connector/status":{type:"request",param:{type:"object",properties:{connector:{type:"string",description:"Optional connector name to filter"}},additionalProperties:!1},result:{type:"object",properties:{connectors:{type:"array",items:{type:"object",properties:{name:{type:"string"},lastSyncedAt:{type:"string"},entityCount:{type:"number"},status:{type:"string",enum:["active","inactive","syncing","error"]},error:{type:"string"}},required:["name","status"],additionalProperties:!1}}},required:["connectors"],additionalProperties:!1}},"connector/action":{type:"request",param:{type:"object",properties:{connector:{type:"string"},action:{type:"string"},input:{type:"object"}},required:["connector","action","input"],additionalProperties:!1},result:{type:"object",properties:{raw:{type:"object"},entity:{type:"object"},documentID:{type:"string"},deletedDocumentID:{type:"string"}},additionalProperties:!1}},"connector/push":{type:"request",param:{type:"object",properties:{connector:{type:"string"},batch:{type:"object",properties:{entities:{type:"array",items:{type:"object"}},deleted:{type:"array",items:{type:"object",properties:{sourceService:{type:"string"},sourceID:{type:"string"}},required:["sourceService","sourceID"]}},checkpoint:{},hasMore:{type:"boolean"}},required:["entities","hasMore"],additionalProperties:!1},checkpoint:{}},required:["connector","batch"],additionalProperties:!1},result:{type:"object",properties:{processed:{type:"number"},failed:{type:"number"},documentIDs:{type:"array",items:{type:"string"}}},required:["processed","failed","documentIDs"],additionalProperties:!1}},"connector/push-complete":{type:"request",param:{type:"object",properties:{connector:{type:"string"},checkpoint:{}},required:["connector","checkpoint"],additionalProperties:!1},result:{type:"object",properties:{acknowledged:{type:"boolean"}},required:["acknowledged"],additionalProperties:!1}},"connector/auth-url":{type:"request",param:{type:"object",properties:{provider:{type:"string"},redirectURL:{type:"string"},connectors:{type:"array",items:{type:"string"}}},required:["provider","redirectURL"],additionalProperties:!1},result:{type:"object",properties:{url:{type:"string"},state:{type:"string"}},required:["url","state"],additionalProperties:!1}},"connector/auth-complete":{type:"request",param:{type:"object",properties:{provider:{type:"string"},code:{type:"string"},state:{type:"string"}},required:["provider","code","state"],additionalProperties:!1},result:{type:"object",properties:{providerName:{type:"string"},accountLabel:{type:"string"},scopes:{type:"array",items:{type:"string"}}},required:["providerName","scopes"],additionalProperties:!1}}};

package/lib/registry.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectorDefinition } from './types.js';
+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/sync/boundary.d.ts

@@ -0,0 +1,4 @@
+import type { SyncBoundary } from '../types.js';
+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/sync/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/types.d.ts

@@ -0,0 +1,123 @@
+import type { ClusterModel } from '@kubun/protocol';
+import type { JSONSchema } from 'json-schema-typed';
+export type SyncBoundary = {
+    maxAge?: string;
+    since?: string;
+    maxEntities?: number;
+};
+export type UserSyncPreferences = {
+    connectorName: string;
+    boundary?: SyncBoundary;
+    excludeChannels?: Array<string>;
+    excludeLabels?: Array<string>;
+};
+export type EntityRecord = Record<string, unknown> & {
+    sourceService: string;
+    sourceID: string;
+};
+export type EntityBatch = {
+    entities: Array<EntityRecord>;
+    deleted?: Array<{
+        sourceService: string;
+        sourceID: string;
+    }>;
+    checkpoint?: unknown;
+    hasMore: boolean;
+};
+export type FetchParams = {
+    boundary: SyncBoundary;
+    checkpoint?: unknown;
+    signal?: AbortSignal;
+};
+export type FetchChangesParams = FetchParams & {
+    lastSyncedAt?: Date;
+};
+export type DataProvider = {
+    fetchAll(params: FetchParams): AsyncIterable<EntityBatch>;
+    fetchChanges(params: FetchChangesParams): AsyncIterable<EntityBatch>;
+    supportedStrategies: Array<'polling' | 'on-demand'>;
+};
+export type WebhookParams = {
+    callbackURL: string;
+    secret?: string;
+};
+export type WebhookRegistration = {
+    id: string;
+    expiresAt?: Date;
+};
+export type ServerDataProvider = DataProvider & {
+    supportedStrategies: Array<'polling' | 'on-demand' | 'webhook'>;
+    registerWebhook?(params: WebhookParams): Promise<WebhookRegistration>;
+    unregisterWebhook?(registrationID: string): Promise<void>;
+};
+export type ClientDataProvider = DataProvider;
+export type DevicePermission = {
+    platform: 'ios' | 'android' | 'web';
+    permission: string;
+    usage: string;
+};
+export type OAuthConnectorAuth = {
+    provider: string;
+    scopes: Array<string>;
+};
+export type DeviceConnectorAuth = {
+    provider: 'device';
+    permissions: Array<DevicePermission>;
+};
+export type ConnectorAuth = OAuthConnectorAuth | DeviceConnectorAuth;
+export type ActionDefinition = {
+    name: string;
+    description: string;
+    input: JSONSchema.Object;
+    output?: JSONSchema.Object;
+    entityModel?: string;
+    requiresCredential: boolean;
+};
+export type ActionResult = {
+    raw?: Record<string, unknown>;
+    entity?: EntityRecord;
+    documentID?: string;
+    deletedDocumentID?: string;
+};
+export type ServerProviderFactory = (config: {
+    credential: unknown;
+    boundary: SyncBoundary;
+}) => ServerDataProvider;
+export type ClientProviderFactory = (config: {
+    boundary: SyncBoundary;
+}) => ClientDataProvider;
+export type ConnectorDefinition = {
+    name: string;
+    version: string;
+    cluster: ClusterModel;
+    syncStrategies: Array<'polling' | 'webhook' | 'on-demand'>;
+    actions?: Array<ActionDefinition>;
+    serverProvider?: ServerProviderFactory;
+    clientProvider?: ClientProviderFactory;
+    graphql?: {
+        mutations?: boolean;
+    };
+    auth: ConnectorAuth;
+};
+export type SyncProgressEvent = {
+    type: 'sync:progress';
+    connectorName: string;
+    phase: 'initial' | 'incremental';
+    entitiesProcessed: number;
+    entitiesFailed: number;
+    currentBatch: number;
+    checkpoint: unknown;
+};
+export type SyncCompleteEvent = {
+    type: 'sync:complete';
+    connectorName: string;
+    totalProcessed: number;
+    totalFailed: number;
+    duration: number;
+};
+export type SyncErrorEvent = {
+    type: 'sync:error';
+    connectorName: string;
+    error: string;
+};
+export type SyncEvent = SyncProgressEvent | SyncCompleteEvent | SyncErrorEvent;

package/lib/types.js

@@ -0,0 +1 @@
+export{};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kubun/connector",
+  "version": "0.5.0",
+  "license": "see LICENSE.md",
+  "keywords": [],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@enkaku/event": "^0.13.0",
+    "@enkaku/protocol": "^0.13.0",
+    "@enkaku/schema": "^0.13.0",
+    "hono": "^4.11.8",
+    "json-schema-typed": "^8.0.2",
+    "@kubun/db": "^0.5.0",
+    "@kubun/logger": "^0.5.0",
+    "@kubun/models": "^0.5.0",
+    "@kubun/scalars": "^0.5.0",
+    "@kubun/protocol": "^0.5.1"
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test:types": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}