@kubun/connector 0.10.0 → 0.12.0

package/lib/cluster-utils.d.ts

@@ -4,3 +4,12 @@ import type { ClustersRecord } from '@kubun/protocol';
  * Use this in providers to tag EntityBatch.modelID at module level.
  */
 export declare function resolveModelID(clusters: ClustersRecord, modelName: string): string;
+/**
+ * Resolve the deduped `urn:kubun:model:<modelID>` for every model a set of
+ * clusters writes. A cluster's `record` holds exactly the concrete models it
+ * imports (interface models such as ExternalEntity are referenced but are not
+ * record members), so its keys are the content-addressed model IDs to scope a
+ * write capability to. Shared by both the client that mints a viewer→server
+ * grant and the server that revokes it, so the two derive the identical set.
+ */
+export declare function clusterModelURNs(clusters: ClustersRecord): Array<string>;

package/lib/cluster-utils.js

@@ -1 +1,32 @@
-export function resolveModelID(e,o){for(let r of Object.values(e)){let e=r.models.findIndex(e=>e.name===o);if(-1!==e){for(let[o,t]of Object.entries(r.record))if(t===e)return o}}throw Error(`Model "${o}" not found in any cluster`)}
+/**
+ * Resolve a model name to its content-addressed model ID across clusters.
+ * Use this in providers to tag EntityBatch.modelID at module level.
+ */ export function resolveModelID(clusters, modelName) {
+    for (const cluster of Object.values(clusters)){
+        const modelIndex = cluster.models.findIndex((m)=>m.name === modelName);
+        if (modelIndex === -1) continue;
+        for (const [id, index] of Object.entries(cluster.record)){
+            if (index === modelIndex) return id;
+        }
+    }
+    throw new Error(`Model "${modelName}" not found in any cluster`);
+}
+/**
+ * Resolve the deduped `urn:kubun:model:<modelID>` for every model a set of
+ * clusters writes. A cluster's `record` holds exactly the concrete models it
+ * imports (interface models such as ExternalEntity are referenced but are not
+ * record members), so its keys are the content-addressed model IDs to scope a
+ * write capability to. Shared by both the client that mints a viewer→server
+ * grant and the server that revokes it, so the two derive the identical set.
+ */ export function clusterModelURNs(clusters) {
+    const urns = [];
+    for (const cluster of Object.values(clusters)){
+        for (const modelID of Object.keys(cluster.record)){
+            const urn = `urn:kubun:model:${modelID}`;
+            if (!urns.includes(urn)) {
+                urns.push(urn);
+            }
+        }
+    }
+    return urns;
+}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { resolveModelID } from './cluster-utils.js';
+export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
 export { connectorClusters, connectorModelIDs } from './models/cluster.js';
 export { externalEntityDefinition } from './models/external-entity.js';
-export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, Credential, CredentialProvider, DataProvider, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchParams, OAuthConnectorAuth, OAuthProviderDefinition, OAuthState, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncProgressEvent, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, TokenResponse, UserSyncPreferences, WebhookParams, WebhookRegistration, } from './types.js';
+export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, Credential, CredentialProvider, DataProvider, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchParams, OAuthConnectorAuth, OAuthProviderDefinition, OAuthState, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressEvent, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, TokenResponse, UserSyncPreferences, WebhookParams, WebhookRegistration, } from './types.js';

package/lib/index.js

@@ -1 +1,3 @@
-export{resolveModelID}from"./cluster-utils.js";export{connectorClusters,connectorModelIDs}from"./models/cluster.js";export{externalEntityDefinition}from"./models/external-entity.js";
+export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
+export { connectorClusters, connectorModelIDs } from './models/cluster.js';
+export { externalEntityDefinition } from './models/external-entity.js';

package/lib/models/cluster.js

@@ -1 +1,11 @@
-import{GraphBuilder as t,GraphModel as e}from"@kubun/protocol";import{externalEntityDefinition as o}from"./external-entity.js";let r=new t;r.add(o);export const connectorClusters=r.build();let n=e.fromClusters({clusters:connectorClusters});export const connectorModelIDs={ExternalEntity:n.aliases.ExternalEntity};
+import { GraphBuilder, GraphModel } from '@kubun/protocol';
+import { externalEntityDefinition } from './external-entity.js';
+const builder = new GraphBuilder();
+builder.add(externalEntityDefinition);
+export const connectorClusters = builder.build();
+const graph = GraphModel.fromClusters({
+    clusters: connectorClusters
+});
+export const connectorModelIDs = {
+    ExternalEntity: graph.aliases.ExternalEntity
+};

package/lib/models/external-entity.js

@@ -1 +1,53 @@
-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:{}};
+import { dateTimeSchema, urlSchema } from '@kubun/scalars';
+/**
+ * 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 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: true,
+        definitions: {
+            SourceService: {
+                type: 'string',
+                title: 'SourceService',
+                minLength: 1,
+                maxLength: 50
+            },
+            SourceID: {
+                type: 'string',
+                title: 'SourceID',
+                minLength: 1,
+                maxLength: 500
+            },
+            SourceURL: urlSchema,
+            DateTime: dateTimeSchema
+        }
+    },
+    fieldsMeta: {}
+};

package/lib/types.d.ts

@@ -42,6 +42,7 @@ export type SyncState = {
     entityCount: number;
     status: SyncStatus;
     error?: string;
+    leaseExpiresAt?: number | null;
 };
 export type SyncStateEntry = SyncState & {
     connectorName: string;
@@ -52,6 +53,8 @@ export type SyncStateStore = {
     set(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
     delete(connectorName: string, ownerDID: string): Promise<void>;
     listForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
+    claimSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<boolean>;
+    renewSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<void>;
 };
 export type SyncBoundary = {
     maxAge?: string;
@@ -162,6 +165,11 @@ export type ConnectorDefinition = {
     };
     auth: ConnectorAuth;
 };
+export type SyncFailureSample = {
+    sourceService: string;
+    sourceID: string;
+    message: string;
+};
 export type SyncProgressEvent = {
     type: 'sync:progress';
     connectorName: string;
@@ -177,11 +185,13 @@ export type SyncCompleteEvent = {
     totalProcessed: number;
     totalFailed: number;
     duration: number;
+    failedSample?: Array<SyncFailureSample>;
 };
 export type SyncErrorEvent = {
     type: 'sync:error';
     connectorName: string;
     error: string;
+    failedSample?: Array<SyncFailureSample>;
 };
 export type SyncEvent = SyncProgressEvent | SyncCompleteEvent | SyncErrorEvent;
 export type ConnectorSyncEventPayload = {
@@ -193,4 +203,5 @@ export type ConnectorSyncEventPayload = {
     totalFailed?: number;
     duration?: number;
     error?: string;
+    failedSample?: Array<SyncFailureSample>;
 };

package/lib/types.js

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

package/package.json

@@ -1,32 +1,32 @@
 {
   "name": "@kubun/connector",
-  "version": "0.10.0",
-  "license": "see LICENSE.md",
+  "version": "0.12.0",
   "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
     "json-schema-typed": "^8.0.2",
-    "@kubun/protocol": "^0.10.0",
-    "@kubun/scalars": "^0.10.0"
+    "@kubun/protocol": "^0.12.0",
+    "@kubun/scalars": "^0.12.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/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": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }