@orgloop/sdk 0.1.0

package/dist/module.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Module types for OrgLoop.
+ *
+ * A module is a bundled workflow: connectors + routes + transforms + SOPs —
+ * installable as a single npm package. Modules reference connectors; they
+ * don't create them. Users wire connectors; modules declare what they need.
+ */
+/** Root module manifest (orgloop-module.yaml) */
+export interface ModuleManifest {
+    apiVersion: string;
+    kind: 'Module';
+    metadata: ModuleMetadata;
+    requires?: ModuleRequirements;
+    parameters?: ModuleParameter[];
+    provides?: ModuleProvides;
+}
+/** Module metadata */
+export interface ModuleMetadata {
+    name: string;
+    description: string;
+    version: string;
+}
+/** What the module requires to function */
+export interface ModuleRequirements {
+    connectors?: ModuleConnectorRequirement[];
+    services?: ModuleServiceRequirement[];
+    credentials?: ModuleCredentialRequirement[];
+    hooks?: ModuleHookRequirement[];
+}
+/** A connector the module needs */
+export interface ModuleConnectorRequirement {
+    type: 'source' | 'actor';
+    id: string;
+    connector: string;
+    required?: boolean;
+    fallback?: 'queue' | 'skip';
+}
+/** A service dependency (informational for doctor/orgctl) */
+export interface ModuleServiceRequirement {
+    name: string;
+    detect?: {
+        http?: string;
+    };
+    install?: {
+        brew?: string;
+        docs?: string;
+    };
+    provides_credentials?: string[];
+}
+/** A credential the module needs (informational for doctor/orgctl) */
+export interface ModuleCredentialRequirement {
+    name: string;
+    description: string;
+    required?: boolean;
+    create_url?: string;
+    validate?: string;
+}
+/** A hook requirement (informational for doctor/orgctl) */
+export interface ModuleHookRequirement {
+    type: string;
+    required?: boolean;
+    scope?: 'global' | 'project';
+}
+/** A parameter the user provides when installing the module */
+export interface ModuleParameter {
+    name: string;
+    description: string;
+    type: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    default?: string | number | boolean;
+}
+/** What the module provides (informational) */
+export interface ModuleProvides {
+    routes?: number;
+    transforms?: number;
+    sops?: number;
+}
+/** A module entry in orgloop.yaml's modules: array */
+export interface InstalledModule {
+    /** npm package name or local path */
+    package: string;
+    /** User-provided parameter values */
+    params: Record<string, string | number | boolean>;
+}
+/** Context available during template expansion */
+export interface ModuleExpansionContext {
+    /** Module metadata */
+    module: {
+        name: string;
+        path: string;
+    };
+    /** User-provided parameter values */
+    params: Record<string, string | number | boolean>;
+}
+/**
+ * Expand `{{ variable }}` placeholders in a string.
+ *
+ * Supports:
+ *   - {{ params.X }}       — user-provided parameter
+ *   - {{ module.name }}    — module name from manifest
+ *   - {{ module.path }}    — resolved filesystem path to the module
+ *
+ * Throws if a referenced variable is not found in the context.
+ */
+export declare function expandTemplate(template: string, context: ModuleExpansionContext): string;
+/**
+ * Deep-expand all string values in an object tree.
+ * Non-string values pass through unchanged.
+ */
+export declare function expandTemplateDeep(value: unknown, context: ModuleExpansionContext): unknown;
+/** JSON Schema for validating orgloop-module.yaml */
+export declare const moduleManifestSchema: {
+    readonly type: "object";
+    readonly required: readonly ["apiVersion", "kind", "metadata"];
+    readonly properties: {
+        readonly apiVersion: {
+            readonly type: "string";
+        };
+        readonly kind: {
+            readonly const: "Module";
+        };
+        readonly metadata: {
+            readonly type: "object";
+            readonly required: readonly ["name", "description", "version"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z0-9][a-z0-9-]*$";
+                };
+                readonly description: {
+                    readonly type: "string";
+                };
+                readonly version: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly requires: {
+            readonly type: "object";
+            readonly properties: {
+                readonly connectors: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["type", "id", "connector"];
+                        readonly properties: {
+                            readonly type: {
+                                readonly enum: readonly ["source", "actor"];
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly connector: {
+                                readonly type: "string";
+                            };
+                            readonly required: {
+                                readonly type: "boolean";
+                            };
+                            readonly fallback: {
+                                readonly enum: readonly ["queue", "skip"];
+                            };
+                        };
+                    };
+                };
+                readonly services: {
+                    readonly type: "array";
+                };
+                readonly credentials: {
+                    readonly type: "array";
+                };
+                readonly hooks: {
+                    readonly type: "array";
+                };
+            };
+        };
+        readonly parameters: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["name", "description", "type"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly type: {
+                        readonly enum: readonly ["string", "number", "boolean"];
+                    };
+                    readonly required: {
+                        readonly type: "boolean";
+                    };
+                    readonly default: {};
+                };
+            };
+        };
+        readonly provides: {
+            readonly type: "object";
+            readonly properties: {
+                readonly routes: {
+                    readonly type: "number";
+                };
+                readonly transforms: {
+                    readonly type: "number";
+                };
+                readonly sops: {
+                    readonly type: "number";
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"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"}

package/dist/module.js

@@ -0,0 +1,125 @@
+/**
+ * Module types for OrgLoop.
+ *
+ * A module is a bundled workflow: connectors + routes + transforms + SOPs —
+ * installable as a single npm package. Modules reference connectors; they
+ * don't create them. Users wire connectors; modules declare what they need.
+ */
+/**
+ * Expand `{{ variable }}` placeholders in a string.
+ *
+ * Supports:
+ *   - {{ params.X }}       — user-provided parameter
+ *   - {{ module.name }}    — module name from manifest
+ *   - {{ module.path }}    — resolved filesystem path to the module
+ *
+ * Throws if a referenced variable is not found in the context.
+ */
+export function expandTemplate(template, context) {
+    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, expr) => {
+        const parts = expr.split('.');
+        if (parts.length !== 2) {
+            throw new Error(`Invalid template expression: {{ ${expr} }}`);
+        }
+        const [namespace, key] = parts;
+        if (namespace === 'module') {
+            const value = context.module[key];
+            if (value === undefined) {
+                throw new Error(`Unknown module variable: {{ ${expr} }}`);
+            }
+            return value;
+        }
+        if (namespace === 'params') {
+            const value = context.params[key];
+            if (value === undefined) {
+                throw new Error(`Missing parameter: {{ ${expr} }}`);
+            }
+            return String(value);
+        }
+        throw new Error(`Unknown namespace "${namespace}" in template expression: {{ ${expr} }}`);
+    });
+}
+/**
+ * Deep-expand all string values in an object tree.
+ * Non-string values pass through unchanged.
+ */
+export function expandTemplateDeep(value, context) {
+    if (typeof value === 'string') {
+        return expandTemplate(value, context);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => expandTemplateDeep(item, context));
+    }
+    if (value !== null && typeof value === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = expandTemplateDeep(v, context);
+        }
+        return result;
+    }
+    return value;
+}
+// ─── Module Manifest JSON Schema ──────────────────────────────────────────────
+/** JSON Schema for validating orgloop-module.yaml */
+export const moduleManifestSchema = {
+    type: 'object',
+    required: ['apiVersion', 'kind', 'metadata'],
+    properties: {
+        apiVersion: { type: 'string' },
+        kind: { const: 'Module' },
+        metadata: {
+            type: 'object',
+            required: ['name', 'description', 'version'],
+            properties: {
+                name: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+                description: { type: 'string' },
+                version: { type: 'string' },
+            },
+        },
+        requires: {
+            type: 'object',
+            properties: {
+                connectors: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['type', 'id', 'connector'],
+                        properties: {
+                            type: { enum: ['source', 'actor'] },
+                            id: { type: 'string' },
+                            connector: { type: 'string' },
+                            required: { type: 'boolean' },
+                            fallback: { enum: ['queue', 'skip'] },
+                        },
+                    },
+                },
+                services: { type: 'array' },
+                credentials: { type: 'array' },
+                hooks: { type: 'array' },
+            },
+        },
+        parameters: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['name', 'description', 'type'],
+                properties: {
+                    name: { type: 'string' },
+                    description: { type: 'string' },
+                    type: { enum: ['string', 'number', 'boolean'] },
+                    required: { type: 'boolean' },
+                    default: {},
+                },
+            },
+        },
+        provides: {
+            type: 'object',
+            properties: {
+                routes: { type: 'number' },
+                transforms: { type: 'number' },
+                sops: { type: 'number' },
+            },
+        },
+    },
+};
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Test harness for OrgLoop plugin authors.
+ *
+ * Provides mock implementations and helpers for testing connectors,
+ * transforms, and loggers in isolation.
+ */
+import type { ActorConnector, DeliveryResult, PollResult, SourceConnector } from './connector.js';
+import { type BuildEventOptions } from './event.js';
+import type { Logger } from './logger.js';
+import type { Transform, TransformContext } from './transform.js';
+import type { ActorConfig, LogEntry, OrgLoopEvent, RouteDeliveryConfig, SourceConfig } from './types.js';
+/**
+ * Mock source connector for testing.
+ * Returns pre-configured events on poll().
+ */
+export declare class MockSource implements SourceConnector {
+    readonly id: string;
+    private events;
+    private pollCount;
+    initialized: boolean;
+    shutdownCalled: boolean;
+    constructor(id?: string);
+    init(_config: SourceConfig): Promise<void>;
+    /** Add events that will be returned on the next poll */
+    addEvents(...events: OrgLoopEvent[]): void;
+    poll(_checkpoint: string | null): Promise<PollResult>;
+    shutdown(): Promise<void>;
+    get totalPolls(): number;
+}
+/**
+ * Mock actor connector for testing.
+ * Records all delivered events for assertion.
+ */
+export declare class MockActor implements ActorConnector {
+    readonly id: string;
+    readonly delivered: Array<{
+        event: OrgLoopEvent;
+        config: RouteDeliveryConfig;
+    }>;
+    private shouldReject;
+    private shouldError;
+    initialized: boolean;
+    shutdownCalled: boolean;
+    constructor(id?: string);
+    init(_config: ActorConfig): Promise<void>;
+    /** Make subsequent deliveries reject */
+    setReject(reject: boolean): void;
+    /** Make subsequent deliveries error */
+    setError(error: boolean): void;
+    deliver(event: OrgLoopEvent, routeConfig: RouteDeliveryConfig): Promise<DeliveryResult>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Mock transform for testing.
+ * Can be configured to pass, drop, or modify events.
+ */
+export declare class MockTransform implements Transform {
+    readonly id: string;
+    readonly processed: Array<{
+        event: OrgLoopEvent;
+        context: TransformContext;
+    }>;
+    private dropAll;
+    private modifier?;
+    initialized: boolean;
+    shutdownCalled: boolean;
+    constructor(id?: string);
+    init(_config: Record<string, unknown>): Promise<void>;
+    /** Make the transform drop all events */
+    setDrop(drop: boolean): void;
+    /** Set a modifier function that transforms events */
+    setModifier(fn: (event: OrgLoopEvent) => OrgLoopEvent): void;
+    execute(event: OrgLoopEvent, context: TransformContext): Promise<OrgLoopEvent | null>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Mock logger for testing.
+ * Records all log entries for assertion.
+ */
+export declare class MockLogger implements Logger {
+    readonly id: string;
+    readonly entries: LogEntry[];
+    initialized: boolean;
+    flushed: boolean;
+    shutdownCalled: boolean;
+    constructor(id?: string);
+    init(_config: Record<string, unknown>): Promise<void>;
+    log(entry: LogEntry): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Get entries for a specific phase */
+    entriesForPhase(phase: LogEntry['phase']): LogEntry[];
+    /** Get entries for a specific event */
+    entriesForEvent(eventId: string): LogEntry[];
+}
+/**
+ * Create a test event with sensible defaults.
+ */
+export declare function createTestEvent(overrides?: Partial<BuildEventOptions>): OrgLoopEvent;
+/**
+ * Create a test transform context with sensible defaults.
+ */
+export declare function createTestContext(overrides?: Partial<TransformContext>): TransformContext;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -0,0 +1,188 @@
+/**
+ * Test harness for OrgLoop plugin authors.
+ *
+ * Provides mock implementations and helpers for testing connectors,
+ * transforms, and loggers in isolation.
+ */
+import { buildEvent } from './event.js';
+// ─── Mock Source ──────────────────────────────────────────────────────────────
+/**
+ * Mock source connector for testing.
+ * Returns pre-configured events on poll().
+ */
+export class MockSource {
+    id;
+    events = [];
+    pollCount = 0;
+    initialized = false;
+    shutdownCalled = false;
+    constructor(id = 'mock-source') {
+        this.id = id;
+    }
+    async init(_config) {
+        this.initialized = true;
+    }
+    /** Add events that will be returned on the next poll */
+    addEvents(...events) {
+        this.events.push(...events);
+    }
+    async poll(_checkpoint) {
+        this.pollCount++;
+        const events = [...this.events];
+        this.events = [];
+        return {
+            events,
+            checkpoint: `mock-checkpoint-${this.pollCount}`,
+        };
+    }
+    async shutdown() {
+        this.shutdownCalled = true;
+    }
+    get totalPolls() {
+        return this.pollCount;
+    }
+}
+// ─── Mock Actor ───────────────────────────────────────────────────────────────
+/**
+ * Mock actor connector for testing.
+ * Records all delivered events for assertion.
+ */
+export class MockActor {
+    id;
+    delivered = [];
+    shouldReject = false;
+    shouldError = false;
+    initialized = false;
+    shutdownCalled = false;
+    constructor(id = 'mock-actor') {
+        this.id = id;
+    }
+    async init(_config) {
+        this.initialized = true;
+    }
+    /** Make subsequent deliveries reject */
+    setReject(reject) {
+        this.shouldReject = reject;
+    }
+    /** Make subsequent deliveries error */
+    setError(error) {
+        this.shouldError = error;
+    }
+    async deliver(event, routeConfig) {
+        this.delivered.push({ event, config: routeConfig });
+        if (this.shouldError) {
+            return { status: 'error', error: new Error('Mock delivery error') };
+        }
+        if (this.shouldReject) {
+            return { status: 'rejected' };
+        }
+        return { status: 'delivered' };
+    }
+    async shutdown() {
+        this.shutdownCalled = true;
+    }
+}
+// ─── Mock Transform ───────────────────────────────────────────────────────────
+/**
+ * Mock transform for testing.
+ * Can be configured to pass, drop, or modify events.
+ */
+export class MockTransform {
+    id;
+    processed = [];
+    dropAll = false;
+    modifier;
+    initialized = false;
+    shutdownCalled = false;
+    constructor(id = 'mock-transform') {
+        this.id = id;
+    }
+    async init(_config) {
+        this.initialized = true;
+    }
+    /** Make the transform drop all events */
+    setDrop(drop) {
+        this.dropAll = drop;
+    }
+    /** Set a modifier function that transforms events */
+    setModifier(fn) {
+        this.modifier = fn;
+    }
+    async execute(event, context) {
+        this.processed.push({ event, context });
+        if (this.dropAll)
+            return null;
+        if (this.modifier)
+            return this.modifier(event);
+        return event;
+    }
+    async shutdown() {
+        this.shutdownCalled = true;
+    }
+}
+// ─── Mock Logger ──────────────────────────────────────────────────────────────
+/**
+ * Mock logger for testing.
+ * Records all log entries for assertion.
+ */
+export class MockLogger {
+    id;
+    entries = [];
+    initialized = false;
+    flushed = false;
+    shutdownCalled = false;
+    constructor(id = 'mock-logger') {
+        this.id = id;
+    }
+    async init(_config) {
+        this.initialized = true;
+    }
+    async log(entry) {
+        this.entries.push(entry);
+    }
+    async flush() {
+        this.flushed = true;
+    }
+    async shutdown() {
+        this.flushed = true;
+        this.shutdownCalled = true;
+    }
+    /** Get entries for a specific phase */
+    entriesForPhase(phase) {
+        return this.entries.filter((e) => e.phase === phase);
+    }
+    /** Get entries for a specific event */
+    entriesForEvent(eventId) {
+        return this.entries.filter((e) => e.event_id === eventId);
+    }
+}
+// ─── Test Event Factory ───────────────────────────────────────────────────────
+/**
+ * Create a test event with sensible defaults.
+ */
+export function createTestEvent(overrides) {
+    return buildEvent({
+        source: 'test-source',
+        type: 'resource.changed',
+        provenance: {
+            platform: 'test',
+            author: 'test-author',
+            author_type: 'team_member',
+        },
+        payload: { test: true },
+        ...overrides,
+    });
+}
+/**
+ * Create a test transform context with sensible defaults.
+ */
+export function createTestContext(overrides) {
+    return {
+        source: 'test-source',
+        target: 'test-actor',
+        eventType: 'resource.changed',
+        routeName: 'test-route',
+        ...overrides,
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}