@arke-institute/klados-testing 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @arke-institute/klados-testing
+
+Test utilities for klados workers on the Arke network.
+
+## Installation
+
+```bash
+npm install --save-dev @arke-institute/klados-testing
+```
+
+## Usage
+
+### Configure the Test Client
+
+Call `configureTestClient` once in your test setup:
+
+```typescript
+import { configureTestClient } from '@arke-institute/klados-testing';
+
+configureTestClient({
+  apiBase: 'https://arke-v1.arke.institute',
+  userKey: process.env.ARKE_USER_KEY!,
+  network: 'test',
+});
+```
+
+### Create Test Fixtures
+
+```typescript
+import {
+  createCollection,
+  createEntity,
+  deleteEntity,
+} from '@arke-institute/klados-testing';
+
+// Create a collection
+const collection = await createCollection({
+  label: 'Test Collection',
+  allowedTypes: ['document'],
+});
+
+// Create an entity in the collection
+const entity = await createEntity({
+  type: 'document',
+  properties: { title: 'Test' },
+  collectionId: collection.id,
+});
+
+// Cleanup
+await deleteEntity(entity.id);
+await deleteEntity(collection.id);
+```
+
+### Invoke and Verify Klados
+
+```typescript
+import {
+  invokeKlados,
+  waitForKladosLog,
+  assertLogCompleted,
+  assertLogHasMessages,
+} from '@arke-institute/klados-testing';
+
+// Invoke a klados
+const result = await invokeKlados({
+  kladosId: 'klados_xxx',
+  targetEntity: entity.id,
+  targetCollection: collection.id,
+  jobCollection: jobCollection.id,
+  confirm: true,
+});
+
+// Wait for completion
+const log = await waitForKladosLog(result.job_collection!, {
+  timeout: 30000,
+  pollInterval: 1000,
+});
+
+// Verify with assertions
+assertLogCompleted(log);
+assertLogHasMessages(log, [
+  { level: 'info', textContains: 'Processing' },
+  { level: 'success', textContains: 'completed' },
+]);
+```
+
+## API Reference
+
+### Configuration
+
+- `configureTestClient(config)` - Configure the test client
+- `getConfig()` - Get current config (throws if not configured)
+- `resetTestClient()` - Reset configuration
+
+### Entity Operations
+
+- `createEntity(options)` - Create an entity
+- `getEntity(id)` - Get an entity by ID
+- `deleteEntity(id)` - Delete an entity
+- `createCollection(options)` - Create a collection
+- `getCollectionEntities(id)` - Get entities in a collection
+
+### Log Utilities
+
+- `getKladosLog(id)` - Get a klados log by ID
+- `getFirstLogFromCollection(id)` - Get first_log relationship from collection
+- `waitForKladosLog(jobCollectionId, options?)` - Wait for log completion
+- `getLogMessages(log)` - Extract messages from log
+- `getLogEntry(log)` - Extract entry details from log
+
+### Klados Invocation
+
+- `invokeKlados(options)` - Invoke a klados worker
+
+### Assertions
+
+- `assertLogCompleted(log)` - Assert log completed successfully
+- `assertLogFailed(log, expectedCode?)` - Assert log failed with error
+- `assertLogHasMessages(log, criteria)` - Assert log contains specific messages
+- `assertLogMessageCount(log, minCount)` - Assert minimum message count
+- `assertLogHasHandoff(log, handoffType)` - Assert log has specific handoff
+
+### Helpers
+
+- `sleep(ms)` - Sleep for duration
+- `log(message, data?)` - Log with timestamp
+- `apiRequest(method, path, body?)` - Make raw API request
+
+## Environment Variables
+
+Your tests should set these environment variables:
+
+- `ARKE_USER_KEY` - User API key (uk_...) for authentication
+- `ARKE_API_BASE` - API base URL (default: https://arke-v1.arke.institute)
+- `ARKE_NETWORK` - Network to use: 'test' or 'main' (default: test)
+
+## License
+
+MIT

package/dist/assertions.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Test assertions for klados logs
+ */
+import type { KladosLogEntry, LogMessageCriteria } from './types';
+/**
+ * Assert that a klados log completed successfully
+ *
+ * @example
+ * ```typescript
+ * const log = await waitForKladosLog(jobCollectionId);
+ * assertLogCompleted(log);
+ * ```
+ *
+ * @param log - The klados log entry (or null)
+ * @throws Error if log is null or has error status
+ */
+export declare function assertLogCompleted(log: KladosLogEntry | null): asserts log is KladosLogEntry;
+/**
+ * Assert that a klados log failed with an error
+ *
+ * @param log - The klados log entry (or null)
+ * @param expectedCode - Optional expected error code
+ * @throws Error if log is null or doesn't have error status
+ */
+export declare function assertLogFailed(log: KladosLogEntry | null, expectedCode?: string): asserts log is KladosLogEntry;
+/**
+ * Assert that a klados log contains specific messages
+ *
+ * @example
+ * ```typescript
+ * assertLogHasMessages(log, [
+ *   { level: 'info', textContains: 'Processing' },
+ *   { level: 'success', textContains: 'completed' },
+ * ]);
+ * ```
+ *
+ * @param log - The klados log entry
+ * @param criteria - Array of message criteria to match
+ * @throws Error if any criteria is not matched
+ */
+export declare function assertLogHasMessages(log: KladosLogEntry, criteria: LogMessageCriteria[]): void;
+/**
+ * Assert that a klados log has at least a minimum number of messages
+ *
+ * @param log - The klados log entry
+ * @param minCount - Minimum number of messages expected
+ */
+export declare function assertLogMessageCount(log: KladosLogEntry, minCount: number): void;
+/**
+ * Assert that a klados log has a handoff of a specific type
+ *
+ * @param log - The klados log entry
+ * @param handoffType - Expected handoff type
+ */
+export declare function assertLogHasHandoff(log: KladosLogEntry, handoffType: 'invoke' | 'scatter' | 'complete' | 'error' | 'none'): void;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAc,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,cAAc,CAkB5F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,GAAG,IAAI,cAAc,CAmB/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,IAAI,CAgBN;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,GACf,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAChE,IAAI,CAUN"}

package/dist/assertions.js

@@ -0,0 +1,121 @@
+/**
+ * Test assertions for klados logs
+ */
+/**
+ * Assert that a klados log completed successfully
+ *
+ * @example
+ * ```typescript
+ * const log = await waitForKladosLog(jobCollectionId);
+ * assertLogCompleted(log);
+ * ```
+ *
+ * @param log - The klados log entry (or null)
+ * @throws Error if log is null or has error status
+ */
+export function assertLogCompleted(log) {
+    if (!log) {
+        throw new Error('Expected klados log but got null');
+    }
+    if (log.properties.status === 'error') {
+        const entry = log.properties.log_data.entry;
+        const errorMsg = entry.error
+            ? `${entry.error.code}: ${entry.error.message}`
+            : 'Unknown error';
+        throw new Error(`Klados log has error status: ${errorMsg}`);
+    }
+    if (log.properties.status !== 'done') {
+        throw new Error(`Expected log status 'done' but got '${log.properties.status}'`);
+    }
+}
+/**
+ * Assert that a klados log failed with an error
+ *
+ * @param log - The klados log entry (or null)
+ * @param expectedCode - Optional expected error code
+ * @throws Error if log is null or doesn't have error status
+ */
+export function assertLogFailed(log, expectedCode) {
+    if (!log) {
+        throw new Error('Expected klados log but got null');
+    }
+    if (log.properties.status !== 'error') {
+        throw new Error(`Expected log status 'error' but got '${log.properties.status}'`);
+    }
+    if (expectedCode) {
+        const actualCode = log.properties.log_data.entry.error?.code;
+        if (actualCode !== expectedCode) {
+            throw new Error(`Expected error code '${expectedCode}' but got '${actualCode}'`);
+        }
+    }
+}
+/**
+ * Assert that a klados log contains specific messages
+ *
+ * @example
+ * ```typescript
+ * assertLogHasMessages(log, [
+ *   { level: 'info', textContains: 'Processing' },
+ *   { level: 'success', textContains: 'completed' },
+ * ]);
+ * ```
+ *
+ * @param log - The klados log entry
+ * @param criteria - Array of message criteria to match
+ * @throws Error if any criteria is not matched
+ */
+export function assertLogHasMessages(log, criteria) {
+    const messages = log.properties.log_data.messages;
+    for (const criterion of criteria) {
+        const found = messages.some((msg) => matchesMessageCriteria(msg, criterion));
+        if (!found) {
+            const criteriaStr = JSON.stringify(criterion);
+            const availableMessages = messages
+                .map((m) => `  - [${m.level}] ${m.message}`)
+                .join('\n');
+            throw new Error(`No message matching criteria ${criteriaStr}.\nAvailable messages:\n${availableMessages}`);
+        }
+    }
+}
+/**
+ * Assert that a klados log has at least a minimum number of messages
+ *
+ * @param log - The klados log entry
+ * @param minCount - Minimum number of messages expected
+ */
+export function assertLogMessageCount(log, minCount) {
+    const actualCount = log.properties.log_data.messages.length;
+    if (actualCount < minCount) {
+        throw new Error(`Expected at least ${minCount} log messages but got ${actualCount}`);
+    }
+}
+/**
+ * Assert that a klados log has a handoff of a specific type
+ *
+ * @param log - The klados log entry
+ * @param handoffType - Expected handoff type
+ */
+export function assertLogHasHandoff(log, handoffType) {
+    const handoffs = log.properties.log_data.entry.handoffs ?? [];
+    const found = handoffs.some((h) => h.type === handoffType);
+    if (!found) {
+        const available = handoffs.map((h) => h.type).join(', ') || '(none)';
+        throw new Error(`Expected handoff of type '${handoffType}' but found: ${available}`);
+    }
+}
+/**
+ * Check if a log message matches the given criteria
+ */
+function matchesMessageCriteria(message, criteria) {
+    if (criteria.level && message.level !== criteria.level) {
+        return false;
+    }
+    if (criteria.textContains && !message.message.includes(criteria.textContains)) {
+        return false;
+    }
+    if (criteria.textEquals && message.message !== criteria.textEquals) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=assertions.js.map

package/dist/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAA0B;IAC3D,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK;YAC1B,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE;YAC/C,CAAC,CAAC,eAAe,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,uCAAuC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAChE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,GAA0B,EAC1B,YAAqB;IAErB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,wCAAwC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CACjE,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC;QAC7D,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,wBAAwB,YAAY,cAAc,UAAU,GAAG,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAmB,EACnB,QAA8B;IAE9B,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAElD,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,sBAAsB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC9C,MAAM,iBAAiB,GAAG,QAAQ;iBAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;iBAC3C,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,KAAK,CACb,gCAAgC,WAAW,2BAA2B,iBAAiB,EAAE,CAC1F,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAmB,EACnB,QAAgB;IAEhB,MAAM,WAAW,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC5D,IAAI,WAAW,GAAG,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,qBAAqB,QAAQ,yBAAyB,WAAW,EAAE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAmB,EACnB,WAAiE;IAEjE,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAE3D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,6BAA6B,WAAW,gBAAgB,SAAS,EAAE,CACpE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,sBAAsB,CAC7B,OAAmB,EACnB,QAA4B;IAE5B,IAAI,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,QAAQ,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * API client utilities for klados testing
+ */
+import type { TestConfig } from './types';
+/**
+ * Configure the test client with API credentials
+ *
+ * This must be called before using any other functions.
+ *
+ * @example
+ * ```typescript
+ * configureTestClient({
+ *   apiBase: 'https://arke-v1.arke.institute',
+ *   userKey: process.env.ARKE_USER_KEY!,
+ *   network: 'test',
+ * });
+ * ```
+ */
+export declare function configureTestClient(config: TestConfig): void;
+/**
+ * Get the current test client configuration
+ *
+ * @throws Error if configureTestClient has not been called
+ */
+export declare function getConfig(): TestConfig;
+/**
+ * Reset the test client configuration (useful for test teardown)
+ */
+export declare function resetTestClient(): void;
+/**
+ * Make an authenticated API request to the Arke API
+ *
+ * @param method - HTTP method
+ * @param path - API path (e.g., '/entities/123')
+ * @param body - Optional request body
+ * @returns Parsed JSON response
+ * @throws Error on API errors or invalid responses
+ */
+export declare function apiRequest<T>(method: string, path: string, body?: Record<string, unknown>): Promise<T>;
+/**
+ * Sleep for a specified duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Log a message with timestamp (useful for test debugging)
+ */
+export declare function log(message: string, data?: unknown): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,UAAU,CAOtC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAOzD"}

package/dist/client.js

@@ -0,0 +1,93 @@
+/**
+ * API client utilities for klados testing
+ */
+// Global configuration
+let globalConfig = null;
+/**
+ * Configure the test client with API credentials
+ *
+ * This must be called before using any other functions.
+ *
+ * @example
+ * ```typescript
+ * configureTestClient({
+ *   apiBase: 'https://arke-v1.arke.institute',
+ *   userKey: process.env.ARKE_USER_KEY!,
+ *   network: 'test',
+ * });
+ * ```
+ */
+export function configureTestClient(config) {
+    globalConfig = config;
+}
+/**
+ * Get the current test client configuration
+ *
+ * @throws Error if configureTestClient has not been called
+ */
+export function getConfig() {
+    if (!globalConfig) {
+        throw new Error('Test client not configured. Call configureTestClient() first.');
+    }
+    return globalConfig;
+}
+/**
+ * Reset the test client configuration (useful for test teardown)
+ */
+export function resetTestClient() {
+    globalConfig = null;
+}
+/**
+ * Make an authenticated API request to the Arke API
+ *
+ * @param method - HTTP method
+ * @param path - API path (e.g., '/entities/123')
+ * @param body - Optional request body
+ * @returns Parsed JSON response
+ * @throws Error on API errors or invalid responses
+ */
+export async function apiRequest(method, path, body) {
+    const config = getConfig();
+    const url = `${config.apiBase}${path}`;
+    const headers = {
+        Authorization: `ApiKey ${config.userKey}`,
+        'Content-Type': 'application/json',
+        'X-Arke-Network': config.network,
+    };
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid JSON response: ${text}`);
+    }
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} - ${text}`);
+    }
+    return data;
+}
+/**
+ * Sleep for a specified duration
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Log a message with timestamp (useful for test debugging)
+ */
+export function log(message, data) {
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    if (data !== undefined) {
+        console.log(`[${timestamp}] ${message}`, JSON.stringify(data, null, 2));
+    }
+    else {
+        console.log(`[${timestamp}] ${message}`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,uBAAuB;AACvB,IAAI,YAAY,GAAsB,IAAI,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,YAAY,GAAG,MAAM,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAc,EACd,IAAY,EACZ,IAA8B;IAE9B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;IACvC,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,MAAM,CAAC,OAAO,EAAE;QACzC,cAAc,EAAE,kBAAkB;QAClC,gBAAgB,EAAE,MAAM,CAAC,OAAO;KACjC,CAAC;IAEF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAChC,MAAM;QACN,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAO,CAAC;IAEZ,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,cAAc,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,IAAc;IACjD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,IAAI,SAAS,KAAK,OAAO,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC"}

package/dist/entities.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Entity and collection operations for klados testing
+ */
+import type { Entity, Collection, CollectionEntities, CreateEntityOptions, CreateCollectionOptions } from './types';
+/**
+ * Create a new entity
+ *
+ * @example
+ * ```typescript
+ * const entity = await createEntity({
+ *   type: 'document',
+ *   properties: { title: 'Test Document' },
+ *   collectionId: collection.id,
+ * });
+ * ```
+ */
+export declare function createEntity(options: CreateEntityOptions): Promise<Entity>;
+/**
+ * Get an entity by ID
+ *
+ * @param id - Entity ID
+ */
+export declare function getEntity(id: string): Promise<Entity>;
+/**
+ * Delete an entity
+ *
+ * @param id - Entity ID to delete
+ */
+export declare function deleteEntity(id: string): Promise<void>;
+/**
+ * Create a new collection
+ *
+ * Uses POST /collections to get proper owner permissions.
+ *
+ * @example
+ * ```typescript
+ * const collection = await createCollection({
+ *   label: 'Test Collection',
+ *   allowedTypes: ['document'],
+ * });
+ * ```
+ */
+export declare function createCollection(options: CreateCollectionOptions): Promise<Collection>;
+/**
+ * Get entities in a collection
+ *
+ * Note: This endpoint has indexing lag. For log discovery, prefer
+ * using `getFirstLogFromCollection` which uses the first_log relationship.
+ *
+ * @param collectionId - Collection ID
+ */
+export declare function getCollectionEntities(collectionId: string): Promise<CollectionEntities>;
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAWhF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3D;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAMrB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAK7B"}

package/dist/entities.js

@@ -0,0 +1,74 @@
+/**
+ * Entity and collection operations for klados testing
+ */
+import { apiRequest } from './client';
+/**
+ * Create a new entity
+ *
+ * @example
+ * ```typescript
+ * const entity = await createEntity({
+ *   type: 'document',
+ *   properties: { title: 'Test Document' },
+ *   collectionId: collection.id,
+ * });
+ * ```
+ */
+export async function createEntity(options) {
+    const body = {
+        type: options.type,
+        properties: options.properties,
+    };
+    if (options.collectionId) {
+        body.collection = options.collectionId;
+    }
+    return apiRequest('POST', '/entities', body);
+}
+/**
+ * Get an entity by ID
+ *
+ * @param id - Entity ID
+ */
+export async function getEntity(id) {
+    return apiRequest('GET', `/entities/${id}`);
+}
+/**
+ * Delete an entity
+ *
+ * @param id - Entity ID to delete
+ */
+export async function deleteEntity(id) {
+    await apiRequest('DELETE', `/entities/${id}`);
+}
+/**
+ * Create a new collection
+ *
+ * Uses POST /collections to get proper owner permissions.
+ *
+ * @example
+ * ```typescript
+ * const collection = await createCollection({
+ *   label: 'Test Collection',
+ *   allowedTypes: ['document'],
+ * });
+ * ```
+ */
+export async function createCollection(options) {
+    return apiRequest('POST', '/collections', {
+        label: options.label,
+        description: options.description,
+        allowed_types: options.allowedTypes,
+    });
+}
+/**
+ * Get entities in a collection
+ *
+ * Note: This endpoint has indexing lag. For log discovery, prefer
+ * using `getFirstLogFromCollection` which uses the first_log relationship.
+ *
+ * @param collectionId - Collection ID
+ */
+export async function getCollectionEntities(collectionId) {
+    return apiRequest('GET', `/collections/${collectionId}/entities`);
+}
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAStC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAA4B;IAC7D,MAAM,IAAI,GAA4B;QACpC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;IAEF,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IACzC,CAAC;IAED,OAAO,UAAU,CAAS,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAAU;IACxC,OAAO,UAAU,CAAS,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAU;IAC3C,MAAM,UAAU,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,OAAO,UAAU,CAAa,MAAM,EAAE,cAAc,EAAE;QACpD,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,aAAa,EAAE,OAAO,CAAC,YAAY;KACpC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,YAAoB;IAEpB,OAAO,UAAU,CACf,KAAK,EACL,gBAAgB,YAAY,WAAW,CACxC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @arke-institute/klados-testing
+ *
+ * Test utilities for klados workers on the Arke network.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   configureTestClient,
+ *   createCollection,
+ *   createEntity,
+ *   deleteEntity,
+ *   invokeKlados,
+ *   waitForKladosLog,
+ *   assertLogCompleted,
+ *   assertLogHasMessages,
+ * } from '@arke-institute/klados-testing';
+ *
+ * // Configure once in test setup
+ * configureTestClient({
+ *   apiBase: 'https://arke-v1.arke.institute',
+ *   userKey: process.env.ARKE_USER_KEY!,
+ *   network: 'test',
+ * });
+ *
+ * // Create test fixtures
+ * const collection = await createCollection({ label: 'Test' });
+ * const entity = await createEntity({
+ *   type: 'document',
+ *   properties: { content: 'test' },
+ *   collectionId: collection.id,
+ * });
+ *
+ * // Invoke klados
+ * const result = await invokeKlados({
+ *   kladosId: 'klados_xxx',
+ *   targetEntity: entity.id,
+ *   targetCollection: collection.id,
+ *   jobCollection: collection.id,
+ * });
+ *
+ * // Wait for completion and verify
+ * const log = await waitForKladosLog(result.job_collection!);
+ * assertLogCompleted(log);
+ * assertLogHasMessages(log, [
+ *   { level: 'info', textContains: 'Processing' },
+ * ]);
+ *
+ * // Cleanup
+ * await deleteEntity(entity.id);
+ * await deleteEntity(collection.id);
+ * ```
+ */
+export { configureTestClient, getConfig, resetTestClient, apiRequest, sleep, log } from './client';
+export { createEntity, getEntity, deleteEntity, createCollection, getCollectionEntities } from './entities';
+export { getKladosLog, getFirstLogFromCollection, waitForKladosLog, getLogMessages, getLogEntry } from './logs';
+export { invokeKlados } from './invoke';
+export { assertLogCompleted, assertLogFailed, assertLogHasMessages, assertLogMessageCount, assertLogHasHandoff, } from './assertions';
+export type { TestConfig, Entity, Collection, CollectionEntities, InvokeResult, LogMessage, KladosLogEntry, CreateEntityOptions, CreateCollectionOptions, InvokeKladosOptions, WaitForLogOptions, LogMessageCriteria, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAGnG,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAG5G,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGhH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,MAAM,EACN,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,64 @@
+/**
+ * @arke-institute/klados-testing
+ *
+ * Test utilities for klados workers on the Arke network.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   configureTestClient,
+ *   createCollection,
+ *   createEntity,
+ *   deleteEntity,
+ *   invokeKlados,
+ *   waitForKladosLog,
+ *   assertLogCompleted,
+ *   assertLogHasMessages,
+ * } from '@arke-institute/klados-testing';
+ *
+ * // Configure once in test setup
+ * configureTestClient({
+ *   apiBase: 'https://arke-v1.arke.institute',
+ *   userKey: process.env.ARKE_USER_KEY!,
+ *   network: 'test',
+ * });
+ *
+ * // Create test fixtures
+ * const collection = await createCollection({ label: 'Test' });
+ * const entity = await createEntity({
+ *   type: 'document',
+ *   properties: { content: 'test' },
+ *   collectionId: collection.id,
+ * });
+ *
+ * // Invoke klados
+ * const result = await invokeKlados({
+ *   kladosId: 'klados_xxx',
+ *   targetEntity: entity.id,
+ *   targetCollection: collection.id,
+ *   jobCollection: collection.id,
+ * });
+ *
+ * // Wait for completion and verify
+ * const log = await waitForKladosLog(result.job_collection!);
+ * assertLogCompleted(log);
+ * assertLogHasMessages(log, [
+ *   { level: 'info', textContains: 'Processing' },
+ * ]);
+ *
+ * // Cleanup
+ * await deleteEntity(entity.id);
+ * await deleteEntity(collection.id);
+ * ```
+ */
+// Configuration
+export { configureTestClient, getConfig, resetTestClient, apiRequest, sleep, log } from './client';
+// Entity operations
+export { createEntity, getEntity, deleteEntity, createCollection, getCollectionEntities } from './entities';
+// Log utilities
+export { getKladosLog, getFirstLogFromCollection, waitForKladosLog, getLogMessages, getLogEntry } from './logs';
+// Klados invocation
+export { invokeKlados } from './invoke';
+// Assertions
+export { assertLogCompleted, assertLogFailed, assertLogHasMessages, assertLogMessageCount, assertLogHasHandoff, } from './assertions';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,gBAAgB;AAChB,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEnG,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE5G,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAEhH,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,aAAa;AACb,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/invoke.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Klados invocation utilities for testing
+ */
+import type { InvokeResult, InvokeKladosOptions } from './types';
+/**
+ * Invoke a klados worker
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeKlados({
+ *   kladosId: 'klados_abc123',
+ *   targetEntity: entity.id,
+ *   targetCollection: collection.id,
+ *   jobCollection: jobCollection.id,
+ *   confirm: true,
+ * });
+ *
+ * if (result.status === 'started') {
+ *   console.log('Job started:', result.job_id);
+ * }
+ * ```
+ *
+ * @param options - Invocation options
+ * @returns The invocation result
+ */
+export declare function invokeKlados(options: InvokeKladosOptions): Promise<InvokeResult>;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAwBvB"}

package/dist/invoke.js

@@ -0,0 +1,43 @@
+/**
+ * Klados invocation utilities for testing
+ */
+import { apiRequest } from './client';
+/**
+ * Invoke a klados worker
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeKlados({
+ *   kladosId: 'klados_abc123',
+ *   targetEntity: entity.id,
+ *   targetCollection: collection.id,
+ *   jobCollection: jobCollection.id,
+ *   confirm: true,
+ * });
+ *
+ * if (result.status === 'started') {
+ *   console.log('Job started:', result.job_id);
+ * }
+ * ```
+ *
+ * @param options - Invocation options
+ * @returns The invocation result
+ */
+export async function invokeKlados(options) {
+    const body = {
+        target_collection: options.targetCollection,
+        job_collection: options.jobCollection,
+        confirm: options.confirm ?? true,
+    };
+    if (options.targetEntity) {
+        body.target_entity = options.targetEntity;
+    }
+    if (options.targetEntities) {
+        body.target_entities = options.targetEntities;
+    }
+    if (options.input) {
+        body.input = options.input;
+    }
+    return apiRequest('POST', `/kladoi/${options.kladosId}/invoke`, body);
+}
+//# sourceMappingURL=invoke.js.map

package/dist/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAA4B;IAE5B,MAAM,IAAI,GAA4B;QACpC,iBAAiB,EAAE,OAAO,CAAC,gBAAgB;QAC3C,cAAc,EAAE,OAAO,CAAC,aAAa;QACrC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;KACjC,CAAC;IAEF,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAC5C,CAAC;IAED,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAChD,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,OAAO,UAAU,CACf,MAAM,EACN,WAAW,OAAO,CAAC,QAAQ,SAAS,EACpC,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/logs.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Klados log utilities for testing
+ */
+import type { KladosLogEntry, WaitForLogOptions } from './types';
+/**
+ * Get a klados log entry by ID
+ *
+ * @param logId - Log entity ID
+ */
+export declare function getKladosLog(logId: string): Promise<KladosLogEntry>;
+/**
+ * Get the first_log relationship from a job collection
+ *
+ * This is more reliable than the indexed /collections/{id}/entities endpoint
+ * because it doesn't have indexing lag.
+ *
+ * @param collectionId - Job collection ID
+ * @returns Log entity ID or null if not found
+ */
+export declare function getFirstLogFromCollection(collectionId: string): Promise<string | null>;
+/**
+ * Wait for and retrieve the klados log from a job collection
+ *
+ * Uses the first_log relationship on the job collection for reliable discovery
+ * (bypasses indexing lag of the /collections/{id}/entities endpoint).
+ *
+ * Waits for the log to reach a terminal state (done or error) before returning.
+ *
+ * @example
+ * ```typescript
+ * const log = await waitForKladosLog(result.jobCollectionId, {
+ *   timeout: 30000,
+ *   pollInterval: 1000,
+ * });
+ *
+ * if (log) {
+ *   console.log('Log status:', log.properties.status);
+ * }
+ * ```
+ *
+ * @param jobCollectionId - Job collection ID to search for logs
+ * @param options - Wait options
+ * @returns The log entry or null if not found within timeout
+ */
+export declare function waitForKladosLog(jobCollectionId: string, options?: WaitForLogOptions): Promise<KladosLogEntry | null>;
+/**
+ * Get all log messages from a klados log
+ *
+ * @param log - The klados log entry
+ */
+export declare function getLogMessages(log: KladosLogEntry): import("./types").LogMessage[];
+/**
+ * Get the log entry details from a klados log
+ *
+ * @param log - The klados log entry
+ */
+export declare function getLogEntry(log: KladosLogEntry): {
+    id: string;
+    job_id: string;
+    klados_id: string;
+    status: "running" | "done" | "error";
+    started_at: string;
+    completed_at?: string;
+    received: {
+        target_entity?: string;
+        target_entities?: string[];
+        target_collection: string;
+        from_logs?: string[];
+        batch?: {
+            slot_id: string;
+            batch_id: string;
+            index: number;
+            total: number;
+        };
+    };
+    handoffs?: Array<{
+        target: string;
+        type: "invoke" | "scatter" | "complete" | "error" | "none";
+        job_id?: string;
+        error?: string;
+    }>;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+};
+//# sourceMappingURL=logs.d.ts.map

package/dist/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAU,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CACpC,eAAe,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA0BhC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,kCAEjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc;;;;;;;;qBAvBpB,CAAC;uBAGtB,CAAC;;iBAOU,CAAC;aAEjB,CAAA;;;;;;;;;;cAW4C,CAAC;aAC1B,CAAC;;;;;;;EACpB"}

package/dist/logs.js

@@ -0,0 +1,92 @@
+/**
+ * Klados log utilities for testing
+ */
+import { apiRequest, sleep } from './client';
+/**
+ * Get a klados log entry by ID
+ *
+ * @param logId - Log entity ID
+ */
+export async function getKladosLog(logId) {
+    return apiRequest('GET', `/entities/${logId}`);
+}
+/**
+ * Get the first_log relationship from a job collection
+ *
+ * This is more reliable than the indexed /collections/{id}/entities endpoint
+ * because it doesn't have indexing lag.
+ *
+ * @param collectionId - Job collection ID
+ * @returns Log entity ID or null if not found
+ */
+export async function getFirstLogFromCollection(collectionId) {
+    const collection = await apiRequest('GET', `/entities/${collectionId}`);
+    // Find the first_log relationship
+    const firstLogRel = collection.relationships?.find((r) => r.predicate === 'first_log');
+    return firstLogRel?.peer ?? null;
+}
+/**
+ * Wait for and retrieve the klados log from a job collection
+ *
+ * Uses the first_log relationship on the job collection for reliable discovery
+ * (bypasses indexing lag of the /collections/{id}/entities endpoint).
+ *
+ * Waits for the log to reach a terminal state (done or error) before returning.
+ *
+ * @example
+ * ```typescript
+ * const log = await waitForKladosLog(result.jobCollectionId, {
+ *   timeout: 30000,
+ *   pollInterval: 1000,
+ * });
+ *
+ * if (log) {
+ *   console.log('Log status:', log.properties.status);
+ * }
+ * ```
+ *
+ * @param jobCollectionId - Job collection ID to search for logs
+ * @param options - Wait options
+ * @returns The log entry or null if not found within timeout
+ */
+export async function waitForKladosLog(jobCollectionId, options) {
+    const timeout = options?.timeout ?? 10000;
+    const pollInterval = options?.pollInterval ?? 1000;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        try {
+            // Use first_log relationship for reliable discovery
+            const firstLogId = await getFirstLogFromCollection(jobCollectionId);
+            if (firstLogId) {
+                const log = await getKladosLog(firstLogId);
+                // Wait for terminal state (done or error)
+                if (log.properties.status === 'done' || log.properties.status === 'error') {
+                    return log;
+                }
+                // Log exists but still running, continue polling
+            }
+        }
+        catch {
+            // Ignore errors during polling, just retry
+        }
+        await sleep(pollInterval);
+    }
+    return null;
+}
+/**
+ * Get all log messages from a klados log
+ *
+ * @param log - The klados log entry
+ */
+export function getLogMessages(log) {
+    return log.properties.log_data.messages;
+}
+/**
+ * Get the log entry details from a klados log
+ *
+ * @param log - The klados log entry
+ */
+export function getLogEntry(log) {
+    return log.properties.log_data.entry;
+}
+//# sourceMappingURL=logs.js.map

package/dist/logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.js","sourceRoot":"","sources":["../src/logs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAG7C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAa;IAC9C,OAAO,UAAU,CAAiB,KAAK,EAAE,aAAa,KAAK,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,YAAoB;IAEpB,MAAM,UAAU,GAAG,MAAM,UAAU,CAAS,KAAK,EAAE,aAAa,YAAY,EAAE,CAAC,CAAC;IAEhF,kCAAkC;IAClC,MAAM,WAAW,GAAG,UAAU,CAAC,aAAa,EAAE,IAAI,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,WAAW,CACnC,CAAC;IAEF,OAAO,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,eAAuB,EACvB,OAA2B;IAE3B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC;IAC1C,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,IAAI,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,oDAAoD;YACpD,MAAM,UAAU,GAAG,MAAM,yBAAyB,CAAC,eAAe,CAAC,CAAC;YAEpE,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;gBAC3C,0CAA0C;gBAC1C,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;oBAC1E,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,iDAAiD;YACnD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;QAED,MAAM,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAmB;IAChD,OAAO,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAmB;IAC7C,OAAO,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC;AACvC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Type definitions for klados testing utilities
+ */
+/**
+ * Configuration for the test client
+ */
+export interface TestConfig {
+    /** Arke API base URL */
+    apiBase: string;
+    /** User API key (uk_...) for authentication */
+    userKey: string;
+    /** Network to operate on ('test' or 'main') */
+    network: 'test' | 'main';
+}
+/**
+ * A generic Arke entity
+ */
+export interface Entity {
+    id: string;
+    type: string;
+    cid: string;
+    properties: Record<string, unknown>;
+    relationships?: Array<{
+        predicate: string;
+        peer: string;
+        peer_type?: string;
+        direction?: 'incoming' | 'outgoing';
+    }>;
+}
+/**
+ * A collection entity
+ */
+export interface Collection {
+    id: string;
+    type: 'collection';
+    cid: string;
+    properties: {
+        label: string;
+        description?: string;
+        allowed_types?: string[];
+    };
+}
+/**
+ * Response from /collections/{id}/entities endpoint
+ */
+export interface CollectionEntities {
+    collection_id: string;
+    entities: Array<{
+        pi: string;
+        type: string;
+        label: string;
+    }>;
+}
+/**
+ * Result of invoking a klados
+ */
+export interface InvokeResult {
+    status: 'started' | 'rejected' | 'pending_confirmation';
+    job_id?: string;
+    job_collection?: string;
+    klados_id?: string;
+    error?: string;
+    message?: string;
+}
+/**
+ * A log message from klados execution
+ */
+export interface LogMessage {
+    level: 'info' | 'warning' | 'error' | 'success';
+    message: string;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+/**
+ * A klados log entry entity
+ */
+export interface KladosLogEntry {
+    id: string;
+    type: string;
+    cid: string;
+    properties: {
+        job_id: string;
+        klados_id: string;
+        status: 'running' | 'done' | 'error';
+        log_data: {
+            agent_id: string;
+            agent_version: string;
+            entry: {
+                id: string;
+                job_id: string;
+                klados_id: string;
+                status: 'running' | 'done' | 'error';
+                started_at: string;
+                completed_at?: string;
+                received: {
+                    target_entity?: string;
+                    target_entities?: string[];
+                    target_collection: string;
+                    from_logs?: string[];
+                    batch?: {
+                        slot_id: string;
+                        batch_id: string;
+                        index: number;
+                        total: number;
+                    };
+                };
+                handoffs?: Array<{
+                    target: string;
+                    type: 'invoke' | 'scatter' | 'complete' | 'error' | 'none';
+                    job_id?: string;
+                    error?: string;
+                }>;
+                error?: {
+                    code: string;
+                    message: string;
+                    retryable: boolean;
+                };
+            };
+            messages: LogMessage[];
+        };
+    };
+}
+/**
+ * Options for creating an entity
+ */
+export interface CreateEntityOptions {
+    type: string;
+    properties: Record<string, unknown>;
+    collectionId?: string;
+}
+/**
+ * Options for creating a collection
+ */
+export interface CreateCollectionOptions {
+    label: string;
+    description?: string;
+    allowedTypes?: string[];
+}
+/**
+ * Options for invoking a klados
+ */
+export interface InvokeKladosOptions {
+    /** Klados ID to invoke */
+    kladosId: string;
+    /** Collection for permission scope (required) */
+    targetCollection: string;
+    /** Single entity to process (for cardinality: 'one') */
+    targetEntity?: string;
+    /** Multiple entities to process (for cardinality: 'many') */
+    targetEntities?: string[];
+    /** Job collection for logs */
+    jobCollection: string;
+    /** Execute (true) or preview (false) */
+    confirm?: boolean;
+    /** Optional input data */
+    input?: Record<string, unknown>;
+}
+/**
+ * Options for waiting for a klados log
+ */
+export interface WaitForLogOptions {
+    /** Maximum time to wait in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Poll interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+}
+/**
+ * Criteria for matching a log message
+ */
+export interface LogMessageCriteria {
+    /** Expected log level */
+    level?: 'info' | 'warning' | 'error' | 'success';
+    /** Text that should be contained in the message */
+    textContains?: string;
+    /** Exact message text match */
+    textEquals?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for klados testing utilities
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@arke-institute/klados-testing",
+  "version": "0.1.0",
+  "description": "Test utilities for klados workers on the Arke network",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@arke-institute/sdk": "^2.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@arke-institute/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arke-institute/sdk": "^2.9.0",
+    "typescript": "^5.7.2"
+  },
+  "keywords": [
+    "arke",
+    "klados",
+    "testing",
+    "workflow",
+    "e2e"
+  ],
+  "author": "Arke Institute",
+  "license": "MIT"
+}