@taodigital/connectors 0.0.0-stage → 1.2.0

package/dist/connectors.test.js

@@ -0,0 +1,407 @@
+"use strict";
+/**
+ * Security-focused tests for all connectors.
+ * Tests SSRF guard, missing credentials, and happy-path API call shape.
+ * No real network calls are made — fetch is mocked globally.
+ *
+ * Requires DATABASE_URL and MIGRATION_DATABASE_URL env vars to satisfy Prisma's
+ * constructor validation (triggered transitively via @taodigital/core → @taodigital/database).
+ * The test script in package.json sets mock values for these.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+// --- helpers -----------------------------------------------------------------
+/** Make a minimal fetch mock that always returns ok with a JSON body. */
+function mockFetch(body, status = 200) {
+    const stub = node_test_1.mock.fn(async (_url, _init) => ({
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+    }));
+    globalThis.fetch = stub;
+    return stub;
+}
+function restoreFetch(original) {
+    globalThis.fetch = original;
+}
+// Private / IMDS addresses that the SSRF guard must block
+const PRIVATE_URLS = [
+    'https://169.254.169.254/latest/meta-data',
+    'https://10.0.0.1',
+    'https://192.168.1.1',
+];
+// =============================================================================
+// Jira
+// =============================================================================
+const jira = __importStar(require("./jira.js"));
+const JIRA_CREDS = {
+    baseUrl: 'https://example.atlassian.net',
+    email: 'test@example.com',
+    apiToken: 'token123',
+    projectKey: 'PROJ',
+};
+(0, node_test_1.test)('jira.listProjects: SSRF guard fires for private baseUrl', async () => {
+    for (const privateUrl of PRIVATE_URLS) {
+        const creds = { ...JIRA_CREDS, baseUrl: privateUrl };
+        await strict_1.default.rejects(() => jira.listProjects(creds), /private or internal|HTTPS/i, `Expected SSRF rejection for ${privateUrl}`);
+    }
+});
+(0, node_test_1.test)('jira.createBug: missing projectKey throws before network call', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({});
+    try {
+        const creds = { ...JIRA_CREDS, projectKey: undefined };
+        await strict_1.default.rejects(() => jira.createBug(creds, { summary: 'Bug', description: 'Desc' }), /projectKey required/i);
+        strict_1.default.equal(stub.mock.calls.length, 0, 'fetch should not be called when projectKey is missing');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('jira.listProjects: happy path — correct auth header and endpoint used', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ values: [{ key: 'PROJ', name: 'Project', id: '1' }] });
+    try {
+        const result = await jira.listProjects(JIRA_CREDS);
+        strict_1.default.equal(result.length, 1);
+        strict_1.default.equal(result[0].key, 'PROJ');
+        strict_1.default.equal(stub.mock.calls.length, 1);
+        const [url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.ok(url.includes('/rest/api/3/project/search'), 'should call JIRA project search');
+        strict_1.default.ok(init.headers.Authorization.startsWith('Basic '), 'Basic auth when no bearerToken');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// Confluence
+// =============================================================================
+const confluence = __importStar(require("./confluence.js"));
+const CONFLUENCE_CREDS = {
+    baseUrl: 'https://example.atlassian.net',
+    email: 'test@example.com',
+    apiToken: 'token123',
+    spaceKey: 'QA',
+};
+(0, node_test_1.test)('confluence.listPages: SSRF guard fires for private baseUrl', async () => {
+    for (const privateUrl of PRIVATE_URLS) {
+        const creds = { ...CONFLUENCE_CREDS, baseUrl: privateUrl };
+        await strict_1.default.rejects(() => confluence.listPages(creds), /private or internal|HTTPS/i, `Expected SSRF rejection for ${privateUrl}`);
+    }
+});
+(0, node_test_1.test)('confluence.testConnection: returns ok:false when server errors, does not throw', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({}, 401);
+    try {
+        const result = await confluence.testConnection(CONFLUENCE_CREDS);
+        strict_1.default.equal(result.ok, false);
+        strict_1.default.ok(result.error?.includes('401'));
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('confluence.listPages: happy path — calls correct endpoint with spaceKey', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ results: [{ id: '123', title: 'Page A' }] });
+    try {
+        const result = await confluence.listPages(CONFLUENCE_CREDS);
+        strict_1.default.equal(result.length, 1);
+        strict_1.default.equal(result[0].title, 'Page A');
+        const [url] = stub.mock.calls[0].arguments;
+        strict_1.default.ok(url.includes('spaceKey=QA'), 'space key should be included in query');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// GitHub
+// =============================================================================
+const github = __importStar(require("./github.js"));
+const GITHUB_CREDS = {
+    token: 'ghp_test_token',
+    repo: 'owner/repo',
+};
+(0, node_test_1.test)('github.testConnection: SSRF guard fires for http:// (non-HTTPS)', async () => {
+    // GitHub always calls api.github.com but assertResolvesToPublicAddress rejects http://
+    // We test this by verifying the module-level check works — since GitHub hardcodes
+    // the URL, the SSRF guard is exercised via assertResolvesToPublicAddress on a known public host.
+    // The guard rejects any http:// scheme, but api.github.com is always https — verify
+    // the normal path proceeds (the guard doesn't reject it as private).
+    const orig = globalThis.fetch;
+    mockFetch({ login: 'octocat' });
+    try {
+        const result = await github.testConnection(GITHUB_CREDS);
+        strict_1.default.equal(result.ok, true);
+        strict_1.default.equal(result.login, 'octocat');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('github.createIssue: missing token causes auth failure (401 treated as error)', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({ message: 'Bad credentials' }, 401);
+    try {
+        await strict_1.default.rejects(() => github.createIssue({ ...GITHUB_CREDS, token: '' }, 'title', 'body'), /GitHub error: 401/);
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('github.listRecentCommits: happy path — correct repo URL and Bearer header', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch([{ sha: 'abc1234', commit: { message: 'Initial', author: { name: 'Dev', date: '2025-01-01' } } }]);
+    try {
+        const result = await github.listRecentCommits(GITHUB_CREDS);
+        strict_1.default.equal(result.length, 1);
+        strict_1.default.equal(result[0].sha, 'abc1234');
+        const [url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.ok(url.includes('/repos/owner/repo/commits'), 'URL must reference the correct repo');
+        strict_1.default.equal(init.headers.Authorization, 'Bearer ghp_test_token');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// Salesforce
+// =============================================================================
+const salesforce = __importStar(require("./salesforce.js"));
+// Use a real, resolvable public hostname for SSRF-guarded connectors.
+// The SSRF guard does actual DNS resolution — fake hostnames cause "Could not
+// resolve destination hostname" before fetch is even reached.
+const SF_CREDS = {
+    instanceUrl: 'https://example.com',
+    clientId: 'clientId123',
+    clientSecret: 'secret123',
+};
+(0, node_test_1.test)('salesforce.listObjects: SSRF guard fires for private instanceUrl', async () => {
+    for (const privateUrl of PRIVATE_URLS) {
+        const creds = { ...SF_CREDS, instanceUrl: privateUrl };
+        await strict_1.default.rejects(() => salesforce.listObjects(creds), /private or internal|HTTPS/i, `Expected SSRF rejection for ${privateUrl}`);
+    }
+});
+(0, node_test_1.test)('salesforce.testConnection: returns ok:false when OAuth token request fails', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({ error: 'invalid_client' }, 401);
+    try {
+        const result = await salesforce.testConnection(SF_CREDS);
+        strict_1.default.equal(result.ok, false);
+        // Error string contains the status code or OAuth error description
+        strict_1.default.ok(result.error != null, 'error field should be set on failure');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('salesforce.createCase: happy path — obtains token then POSTs case', async () => {
+    const orig = globalThis.fetch;
+    // First call = OAuth token endpoint, second call = create case
+    let callCount = 0;
+    globalThis.fetch = async (_url, _init) => {
+        callCount++;
+        if (callCount === 1) {
+            // Salesforce token endpoint
+            return { ok: true, status: 200, json: async () => ({ access_token: 'tok' }), text: async () => '' };
+        }
+        return { ok: true, status: 200, json: async () => ({ id: 'case001' }), text: async () => '' };
+    };
+    try {
+        const result = await salesforce.createCase(SF_CREDS, { subject: 'Test', description: 'Desc' });
+        strict_1.default.equal(result.id, 'case001');
+        strict_1.default.ok(result.url.includes('case001'));
+        strict_1.default.equal(callCount, 2, 'should make OAuth token call then case creation call');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// ServiceNow
+// =============================================================================
+const servicenow = __importStar(require("./servicenow.js"));
+const SN_CREDS = {
+    instanceUrl: 'https://example.com',
+    username: 'admin',
+    password: 'pass123',
+};
+(0, node_test_1.test)('servicenow.createIncident: SSRF guard fires for private instanceUrl', async () => {
+    for (const privateUrl of PRIVATE_URLS) {
+        const creds = { ...SN_CREDS, instanceUrl: privateUrl };
+        await strict_1.default.rejects(() => servicenow.createIncident(creds, { shortDescription: 'Test', description: 'Desc' }), /private or internal|HTTPS/i, `Expected SSRF rejection for ${privateUrl}`);
+    }
+});
+(0, node_test_1.test)('servicenow.testConnection: returns ok:false when server returns 401', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({ error: 'Unauthorized' }, 401);
+    try {
+        const result = await servicenow.testConnection(SN_CREDS);
+        strict_1.default.equal(result.ok, false);
+        strict_1.default.ok(result.error != null, 'error field should be set on failure');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('servicenow.createIncident: happy path — POSTs to incident table with correct fields', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ result: { sys_id: 'sys001', number: 'INC0001' } });
+    try {
+        const result = await servicenow.createIncident(SN_CREDS, {
+            shortDescription: 'Login broken',
+            description: 'Full description',
+            urgency: 1,
+        });
+        strict_1.default.equal(result.sysId, 'sys001');
+        strict_1.default.equal(result.number, 'INC0001');
+        const [url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.ok(url.includes('/api/now/table/incident'), 'must POST to incident table');
+        const body = JSON.parse(init.body);
+        strict_1.default.equal(body.urgency, '1');
+        strict_1.default.equal(body.short_description, 'Login broken');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// Figma
+// =============================================================================
+const figma = __importStar(require("./figma.js"));
+const FIGMA_CREDS = {
+    accessToken: 'figd_test_token',
+    fileKey: 'testFileKey123',
+};
+(0, node_test_1.test)('figma.testConnection: returns ok:false when token is rejected (403)', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({ message: 'Forbidden' }, 403);
+    try {
+        const result = await figma.testConnection(FIGMA_CREDS);
+        strict_1.default.equal(result.ok, false);
+        strict_1.default.ok(result.error?.includes('403'));
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('figma.testConnection: uses X-Figma-Token header for PAT', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ handle: 'design_user', email: 'design@example.com' });
+    try {
+        const result = await figma.testConnection(FIGMA_CREDS);
+        strict_1.default.equal(result.ok, true);
+        strict_1.default.equal(result.name, 'design_user');
+        const [_url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.equal(init.headers['X-Figma-Token'], 'figd_test_token', 'PAT must be sent as X-Figma-Token');
+        strict_1.default.equal(init.headers.Authorization, undefined, 'no Bearer header for PAT');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('figma.testConnection: uses Bearer header for OAuth token', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ handle: 'oauth_user' });
+    try {
+        await figma.testConnection({ ...FIGMA_CREDS, oauthToken: 'oauth_token_abc' });
+        const [_url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.equal(init.headers.Authorization, 'Bearer oauth_token_abc');
+        strict_1.default.equal(init.headers['X-Figma-Token'], undefined, 'no PAT header when oauthToken is set');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+// =============================================================================
+// PagerDuty
+// =============================================================================
+const pagerduty = __importStar(require("./pagerduty.js"));
+const PD_CREDS = {
+    apiKey: 'pd_api_key_test',
+    serviceId: 'SVCABC',
+};
+(0, node_test_1.test)('pagerduty.createIncident: missing serviceId throws before network call', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({});
+    try {
+        const creds = { apiKey: 'pd_api_key_test' };
+        await strict_1.default.rejects(() => pagerduty.createIncident(creds, { title: 'Alert', body: 'Details', severity: 'critical' }), /serviceId is required/i);
+        strict_1.default.equal(stub.mock.calls.length, 0, 'fetch should not be called when serviceId is missing');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('pagerduty.testConnection: returns ok:false on 401', async () => {
+    const orig = globalThis.fetch;
+    mockFetch({ error: 'Invalid credentials' }, 401);
+    try {
+        const result = await pagerduty.testConnection(PD_CREDS);
+        strict_1.default.equal(result.ok, false);
+        strict_1.default.ok(result.error?.includes('401'));
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});
+(0, node_test_1.test)('pagerduty.createIncident: happy path — correct token header and incident shape', async () => {
+    const orig = globalThis.fetch;
+    const stub = mockFetch({ incident: { id: 'INC001', html_url: 'https://example.pagerduty.com/incidents/INC001' } });
+    try {
+        const result = await pagerduty.createIncident(PD_CREDS, {
+            title: 'Critical failure',
+            body: 'System down',
+            severity: 'critical',
+        });
+        strict_1.default.equal(result.id, 'INC001');
+        const [url, init] = stub.mock.calls[0].arguments;
+        strict_1.default.ok(url.includes('pagerduty.com/incidents'), 'must post to PD incidents endpoint');
+        strict_1.default.ok(init.headers.Authorization.startsWith('Token token='), 'PD uses Token auth scheme');
+        const body = JSON.parse(init.body);
+        strict_1.default.equal(body.incident.urgency, 'high', 'critical severity maps to high urgency');
+    }
+    finally {
+        restoreFetch(orig);
+    }
+});

package/dist/figma.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Figma connector — reads design files and extracts screens + components.
+ * Access token stored encrypted per project.
+ */
+export interface FigmaCredentials {
+    accessToken: string;
+    fileKey?: string;
+    oauthToken?: string;
+}
+export declare function testConnection(creds: FigmaCredentials): Promise<{
+    ok: boolean;
+    name?: string;
+    error?: string;
+}>;
+export declare function getFile(creds: FigmaCredentials, fileKey?: string): Promise<any>;
+export interface ListScreensOptions {
+    nodeTypes?: string[];
+    excludePrefixes?: string[];
+}
+/** Extract top-level frames (screens) from a Figma file.
+ *  Only takes DIRECT children of each page — not recursively nested components.
+ *  This gives you actual screens (what designers think of as a screen),
+ *  not every sub-component and icon frame inside them (which can number in the hundreds).
+ */
+export declare function listScreens(creds: FigmaCredentials, fileKey?: string, options?: ListScreensOptions): Promise<{
+    id: string;
+    name: string;
+    type: string;
+    node: any;
+}[]>;
+export interface GetScreenImagesOptions {
+    imageScale?: number;
+    chunkSize?: number;
+}
+/** Get image URLs for specific node IDs in a Figma file. */
+export declare function getScreenImages(creds: FigmaCredentials, fileKey: string, nodeIds: string[], scale?: number, options?: GetScreenImagesOptions): Promise<Record<string, string>>;
+export interface FigmaElement {
+    name: string;
+    type: string;
+    description?: string;
+    isInteractive: boolean;
+    reactions?: any[];
+    destinationIds?: string[];
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    componentId?: string;
+}
+/** Extract interactive elements from a Figma frame node.
+ *  Uses reactions/interactions as the primary interactivity signal.
+ *  FRAME and GROUP are included — they cover buttons, cards, modals, navbars.
+ *  Primitive types (RECTANGLE, TEXT, etc.) are only collected when they have explicit reactions.
+ */
+export declare function extractElements(node: any): FigmaElement[];

package/dist/figma.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Figma connector — reads design files and extracts screens + components.
+ * Access token stored encrypted per project.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testConnection = testConnection;
+exports.getFile = getFile;
+exports.listScreens = listScreens;
+exports.getScreenImages = getScreenImages;
+exports.extractElements = extractElements;
+function headers(creds) {
+    if (creds.oauthToken) {
+        return { Authorization: `Bearer ${creds.oauthToken}`, 'Content-Type': 'application/json' };
+    }
+    return { 'X-Figma-Token': creds.accessToken, 'Content-Type': 'application/json' };
+}
+async function testConnection(creds) {
+    try {
+        const res = await fetch('https://api.figma.com/v1/me', { headers: headers(creds) });
+        if (!res.ok)
+            return { ok: false, error: `Figma returned ${res.status}` };
+        const data = (await res.json());
+        return { ok: true, name: data.handle };
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+}
+async function getFile(creds, fileKey) {
+    const key = fileKey ?? creds.fileKey;
+    if (!key)
+        throw new Error('Figma file key is required.');
+    const res = await fetch(`https://api.figma.com/v1/files/${key}`, { headers: headers(creds) });
+    if (!res.ok)
+        throw new Error(`Figma error: ${res.status}`);
+    return res.json();
+}
+/** Extract top-level frames (screens) from a Figma file.
+ *  Only takes DIRECT children of each page — not recursively nested components.
+ *  This gives you actual screens (what designers think of as a screen),
+ *  not every sub-component and icon frame inside them (which can number in the hundreds).
+ */
+async function listScreens(creds, fileKey, options = {}) {
+    const file = await getFile(creds, fileKey);
+    const screens = [];
+    const nodeTypes = options.nodeTypes ?? ['FRAME', 'COMPONENT', 'SECTION'];
+    const excludePrefixes = options.excludePrefixes ?? ['_', '.'];
+    (file.document?.children ?? []).forEach((page) => {
+        // Only direct children of pages = top-level frames = actual screens
+        (page.children ?? []).forEach((node) => {
+            if (nodeTypes.includes(node.type)) {
+                // Skip utility frames: those starting with _ or . (designer convention for hidden/utility)
+                if (!excludePrefixes.some((p) => node.name.startsWith(p))) {
+                    screens.push({ id: node.id, name: node.name, type: node.type, node });
+                }
+            }
+        });
+    });
+    return screens;
+}
+/** Get image URLs for specific node IDs in a Figma file. */
+async function getScreenImages(creds, fileKey, nodeIds, scale, options = {}) {
+    // Batch into chunks of 50 to avoid HTTP 414 (URI Too Long) on large files
+    const { getSystemConfig } = await import('@taodigital/core');
+    const figmaCfg = await getSystemConfig('connectors_figma');
+    const resolvedScale = options.imageScale ?? scale ?? parseInt(String(figmaCfg?.imageScale ?? '2'), 10);
+    const CHUNK = options.chunkSize ?? parseInt(String(figmaCfg?.chunkSize ?? '50'), 10);
+    const result = {};
+    for (let i = 0; i < nodeIds.length; i += CHUNK) {
+        const chunk = nodeIds.slice(i, i + CHUNK);
+        const ids = chunk.join(',');
+        const res = await fetch(`https://api.figma.com/v1/images/${fileKey}?ids=${encodeURIComponent(ids)}&scale=${resolvedScale}&format=png`, { headers: headers(creds) });
+        if (!res.ok)
+            throw new Error(`Figma error: ${res.status}`);
+        const data = (await res.json());
+        Object.assign(result, data.images);
+    }
+    return result; // nodeId → image URL
+}
+/** Extract interactive elements from a Figma frame node.
+ *  Uses reactions/interactions as the primary interactivity signal.
+ *  FRAME and GROUP are included — they cover buttons, cards, modals, navbars.
+ *  Primitive types (RECTANGLE, TEXT, etc.) are only collected when they have explicit reactions.
+ */
+function extractElements(node) {
+    const elements = [];
+    const CONTAINER_TYPES = new Set(['FRAME', 'GROUP', 'COMPONENT', 'INSTANCE', 'COMPONENT_SET']);
+    const PRIMITIVE_TYPES = new Set(['RECTANGLE', 'ELLIPSE', 'TEXT', 'VECTOR', 'STAR', 'POLYGON', 'LINE']);
+    function destinationIds(reactions) {
+        const ids = [];
+        for (const r of reactions) {
+            const actions = r.actions ?? (r.action ? [r.action] : []);
+            for (const a of actions) {
+                if (a?.destinationId)
+                    ids.push(a.destinationId);
+            }
+        }
+        return ids;
+    }
+    function walk(n) {
+        if (!n?.name || n.name.startsWith('_') || n.name.startsWith('.')) {
+            (n?.children ?? []).forEach(walk);
+            return;
+        }
+        // REST API uses `interactions`; Plugin API uses `reactions` — support both.
+        const reactions = n.interactions ?? n.reactions ?? [];
+        const hasReactions = reactions.length > 0;
+        if (CONTAINER_TYPES.has(n.type)) {
+            elements.push({
+                name: n.name,
+                type: n.type,
+                description: n.description ?? undefined,
+                isInteractive: hasReactions,
+                ...(hasReactions ? { reactions, destinationIds: destinationIds(reactions) } : {}),
+                boundingBox: n.absoluteBoundingBox ?? undefined,
+                componentId: n.componentId ?? undefined,
+            });
+            // Don't recurse into INSTANCE internals — the instance is the unit of interest.
+            if (n.type !== 'INSTANCE')
+                (n.children ?? []).forEach(walk);
+        }
+        else if (PRIMITIVE_TYPES.has(n.type) && hasReactions) {
+            // Only collect primitives that are explicitly interactive (e.g. clickable text links).
+            elements.push({
+                name: n.name,
+                type: n.type,
+                isInteractive: true,
+                reactions,
+                destinationIds: destinationIds(reactions),
+                boundingBox: n.absoluteBoundingBox ?? undefined,
+            });
+            (n.children ?? []).forEach(walk);
+        }
+        else {
+            (n.children ?? []).forEach(walk);
+        }
+    }
+    walk(node);
+    return elements;
+}

package/dist/github.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GitHub connector — credentials passed in, never read from env.
+ * Token is stored encrypted in Connector.config per project.
+ */
+export interface GitHubCredentials {
+    token: string;
+    repo: string;
+    defaultBranch?: string;
+}
+/** Test that the stored credentials actually work. */
+export declare function testConnection(creds: GitHubCredentials): Promise<{
+    ok: boolean;
+    login?: string;
+    error?: string;
+}>;
+export declare function listRecentCommits(creds: GitHubCredentials, branch?: string): Promise<{
+    sha: any;
+    message: any;
+    author: any;
+    date: any;
+}[]>;
+export declare function createIssue(creds: GitHubCredentials, title: string, body: string, labels?: string[], opts?: {
+    defaultLabels?: string[];
+}): Promise<{
+    number: any;
+    url: any;
+    title: any;
+}>;
+export declare function listPullRequests(creds: GitHubCredentials, state?: 'open' | 'closed' | 'all'): Promise<{
+    number: any;
+    title: any;
+    state: any;
+    branch: any;
+    url: any;
+}[]>;
+/**
+ * Push (create or update) a single file in a GitHub repository.
+ * Uses the GitHub Contents API (PUT /repos/:owner/:repo/contents/:path).
+ */
+export declare function pushFile(creds: GitHubCredentials, filePath: string, content: string, commitMessage: string, branch?: string): Promise<{
+    url: string;
+    sha: string;
+}>;