@ruvos/handler-sdk 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @ruvos/handler-sdk
+
+SDK for building custom pipeline handlers for the [Ruvos](https://ruvos.io) healthcare data exchange platform.
+
+Handlers let you intercept and process FHIR resources at three stages of the Ruvos data pipeline:
+- **`post_downstream_fetch`** — after data is fetched from an external source
+- **`pre_store`** — before data is encrypted and stored
+- **`post_store`** — after data is persisted
+
+## Installation
+
+```bash
+npm install @ruvos/handler-sdk
+```
+
+## Quick Start
+
+### Scaffold a new handler project
+
+```bash
+npx @ruvos/handler-sdk create-handler my-handler
+cd ruvos-handler-my-handler
+npm install
+```
+
+This generates a complete project with TypeScript config, esbuild bundling, Terraform infrastructure, and a GitLab CI pipeline.
+
+### Write a handler
+
+```typescript
+import { createHandler, type HandlerInput, type HandlerOutcome } from "@ruvos/handler-sdk";
+
+async function handle(input: HandlerInput): Promise<HandlerOutcome> {
+  const { stage, payload, tenantId, connectorType } = input;
+
+  // Transform: modify resources before storage
+  if (stage === "pre_store" && payload.resources) {
+    const enriched = payload.resources.map((r) => ({
+      ...r,
+      meta: { ...r.meta, tag: [{ code: "reviewed", display: "Reviewed by handler" }] },
+    }));
+    return { action: "transform", resources: enriched };
+  }
+
+  // Passthrough: continue normal pipeline
+  return { action: "passthrough" };
+}
+
+export const handler = createHandler({ handlerId: "my-handler" }, handle);
+```
+
+## Handler Outcomes
+
+Every handler must return one of five outcomes:
+
+| Outcome | Description |
+|---|---|
+| `passthrough` | Continue normal pipeline processing |
+| `transform` | Replace resources with a modified set |
+| `route_to` | Forward the payload to an HTTPS URL (skip normal storage) |
+| `requeue` | Retry processing later with an optional delay |
+| `fail` | Abort the job with a reason |
+
+```typescript
+// passthrough
+return { action: "passthrough" };
+
+// transform
+return { action: "transform", resources: modifiedResources, metadata: { source: "enriched" } };
+
+// route_to
+return { action: "route_to", url: "https://my-service.example.com/ingest", body: payload };
+
+// requeue
+return { action: "requeue", delaySeconds: 30 };
+
+// fail
+return { action: "fail", reason: "Missing required patient identifier" };
+```
+
+## API Reference
+
+### `createHandler(options, fn)`
+
+Wraps a handler function with logging, timeout, and outcome validation.
+
+```typescript
+import { createHandler } from "@ruvos/handler-sdk";
+
+export const handler = createHandler(
+  { handlerId: "my-handler", timeoutMs: 60_000 },
+  async (input) => { /* ... */ }
+);
+```
+
+**Options:**
+- `handlerId` — unique identifier for this handler
+- `timeoutMs` — execution timeout (default: 120,000ms)
+
+### `parseCcda(xml)`
+
+Parses a C-CDA XML document into FHIR resources (Patient + Composition).
+
+```typescript
+import { parseCcda } from "@ruvos/handler-sdk";
+
+const resources = parseCcda(xmlString);
+// [{ resourceType: "Patient", ... }, { resourceType: "Composition", ... }]
+```
+
+### `validateOutcome(value)`
+
+Validates that a handler outcome has the correct structure. Called automatically by `createHandler`, but available for testing.
+
+```typescript
+import { validateOutcome, HandlerValidationError } from "@ruvos/handler-sdk";
+
+try {
+  const validated = validateOutcome(result);
+} catch (err) {
+  if (err instanceof HandlerValidationError) {
+    console.error("Invalid outcome:", err.message);
+  }
+}
+```
+
+### `createHandlerLogger(context)`
+
+Creates a structured JSON logger for use within handlers.
+
+```typescript
+import { createHandlerLogger } from "@ruvos/handler-sdk";
+
+const logger = createHandlerLogger({
+  handlerId: "my-handler",
+  correlationId: input.correlationId,
+  tenantId: input.tenantId,
+  stage: input.stage,
+});
+
+logger.info("processing_resources", { count: input.payload.resources?.length });
+```
+
+## Types
+
+```typescript
+type HookStage = "post_downstream_fetch" | "pre_store" | "post_store";
+
+interface HandlerInput {
+  stage: HookStage;
+  tenantId: string;
+  jobId: string;
+  correlationId: string;
+  connectorType: string;
+  config?: Record<string, unknown>;
+  payload: {
+    resources?: FHIRResource[];
+    metadata?: Record<string, unknown>;
+    s3Key?: string;
+  };
+}
+
+type HandlerOutcome =
+  | { action: "passthrough" }
+  | { action: "transform"; resources: FHIRResource[]; metadata?: Record<string, unknown> }
+  | { action: "route_to"; url: string; method?: string; headers?: Record<string, string>; body: unknown }
+  | { action: "requeue"; delaySeconds?: number }
+  | { action: "fail"; reason: string };
+
+interface FHIRResource {
+  resourceType: string;
+  id?: string;
+  [key: string]: unknown;
+}
+```
+
+## License
+
+MIT

package/dist/ccda.d.ts

@@ -0,0 +1,3 @@
+import type { FHIRResource } from "./types.js";
+export declare function parseCcda(xml: string): FHIRResource[];
+//# sourceMappingURL=ccda.d.ts.map

package/dist/ccda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccda.d.ts","sourceRoot":"","sources":["../src/ccda.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8F/C,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAYrD"}

package/dist/ccda.js

@@ -0,0 +1,87 @@
+function extractTagContent(xml, tag) {
+    const results = [];
+    const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "gi");
+    let match;
+    while ((match = regex.exec(xml)) !== null) {
+        results.push(match[1]);
+    }
+    return results;
+}
+function extractAttribute(xml, tag, attr) {
+    const regex = new RegExp(`<${tag}[^>]*?\\s${attr}="([^"]*)"`, "i");
+    const match = regex.exec(xml);
+    return match?.[1];
+}
+function extractPatient(xml) {
+    const patientRole = extractTagContent(xml, "patientRole")[0];
+    if (!patientRole)
+        return null;
+    const names = extractTagContent(patientRole, "name");
+    const given = names.length > 0 ? extractTagContent(names[0], "given") : [];
+    const family = names.length > 0 ? extractTagContent(names[0], "family") : [];
+    const gender = extractAttribute(patientRole, "administrativeGenderCode", "code");
+    const birthTime = extractAttribute(patientRole, "birthTime", "value");
+    const addrs = extractTagContent(patientRole, "addr");
+    let address;
+    if (addrs.length > 0) {
+        const streetLines = extractTagContent(addrs[0], "streetAddressLine");
+        const city = extractTagContent(addrs[0], "city")[0];
+        const state = extractTagContent(addrs[0], "state")[0];
+        const postalCode = extractTagContent(addrs[0], "postalCode")[0];
+        address = {
+            ...(streetLines.length > 0 ? { line: streetLines } : {}),
+            ...(city ? { city } : {}),
+            ...(state ? { state } : {}),
+            ...(postalCode ? { postalCode } : {}),
+        };
+    }
+    const genderMap = { M: "male", F: "female", UN: "unknown" };
+    return {
+        resourceType: "Patient",
+        name: [{ given, family: family[0] ?? "" }],
+        ...(gender ? { gender: genderMap[gender] ?? "unknown" } : {}),
+        ...(birthTime ? { birthDate: `${birthTime.slice(0, 4)}-${birthTime.slice(4, 6)}-${birthTime.slice(6, 8)}` } : {}),
+        ...(address ? { address: [address] } : {}),
+    };
+}
+function extractSections(xml) {
+    const components = extractTagContent(xml, "component");
+    const sections = [];
+    for (const comp of components) {
+        const sectionBlocks = extractTagContent(comp, "section");
+        for (const sec of sectionBlocks) {
+            const code = extractAttribute(sec, "code", "code") ?? "unknown";
+            const titles = extractTagContent(sec, "title");
+            const title = titles[0] ?? "Untitled Section";
+            const texts = extractTagContent(sec, "text");
+            sections.push({ code, title, text: texts[0] });
+        }
+    }
+    return sections;
+}
+function sectionToComposition(sections) {
+    return {
+        resourceType: "Composition",
+        status: "final",
+        type: {
+            coding: [{ system: "http://loinc.org", code: "34133-9", display: "Summary of episode note" }],
+        },
+        section: sections.map((s) => ({
+            title: s.title,
+            code: { coding: [{ code: s.code }] },
+            text: s.text ? { status: "generated", div: `<div xmlns="http://www.w3.org/1999/xhtml">${s.text}</div>` } : undefined,
+        })),
+    };
+}
+export function parseCcda(xml) {
+    const resources = [];
+    const patient = extractPatient(xml);
+    if (patient)
+        resources.push(patient);
+    const sections = extractSections(xml);
+    if (sections.length > 0) {
+        resources.push(sectionToComposition(sections));
+    }
+    return resources;
+}
+//# sourceMappingURL=ccda.js.map

package/dist/ccda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccda.js","sourceRoot":"","sources":["../src/ccda.ts"],"names":[],"mappings":"AAQA,SAAS,iBAAiB,CAAC,GAAW,EAAE,GAAW;IACjD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,yBAAyB,GAAG,GAAG,EAAE,IAAI,CAAC,CAAC;IACvE,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY;IAC9D,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,YAAY,IAAI,YAAY,EAAE,GAAG,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,WAAW,GAAG,iBAAiB,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,KAAK,GAAG,iBAAiB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE9E,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,0BAA0B,EAAE,MAAM,CAAC,CAAC;IACjF,MAAM,SAAS,GAAG,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAEtE,MAAM,KAAK,GAAG,iBAAiB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,OAA4C,CAAC;IACjD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,mBAAmB,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,OAAO,GAAG;YACR,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtC,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAA2B,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;IAEpF,OAAO;QACL,YAAY,EAAE,SAAS;QACvB,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjH,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC;YAChE,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC;YAC9C,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,oBAAoB,CAAC,QAAuB;IACnD,OAAO;QACL,YAAY,EAAE,aAAa;QAC3B,MAAM,EAAE,OAAO;QACf,IAAI,EAAE;YACJ,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC;SAC9F;QACD,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5B,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE;YACpC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,6CAA6C,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS;SACrH,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,SAAS,GAAmB,EAAE,CAAC;IAErC,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO;QAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,SAAS,CAAC,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cli/create-handler.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=create-handler.d.ts.map

package/dist/cli/create-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-handler.d.ts","sourceRoot":"","sources":["../../src/cli/create-handler.ts"],"names":[],"mappings":""}

package/dist/cli/create-handler.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const name = process.argv[2];
+if (!name) {
+    console.error("Usage: create-handler <handler-name>");
+    console.error("Example: create-handler ccda-parser");
+    process.exit(1);
+}
+const slug = name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+const dir = join(process.cwd(), `ruvos-handler-${slug}`);
+mkdirSync(join(dir, "src"), { recursive: true });
+mkdirSync(join(dir, "infra"), { recursive: true });
+writeFileSync(join(dir, "package.json"), JSON.stringify({
+    name: `@ruvos/handler-${slug}`,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+        build: "tsc -b && node esbuild.config.mjs",
+        clean: "rm -rf dist",
+    },
+    dependencies: {
+        "@ruvos/handler-sdk": "^0.1.0",
+    },
+    devDependencies: {
+        "@types/node": "^25.5.2",
+        esbuild: "^0.25.0",
+        typescript: "^5.7.0",
+    },
+}, null, 2) + "\n");
+writeFileSync(join(dir, "tsconfig.json"), JSON.stringify({
+    compilerOptions: {
+        target: "ES2022",
+        lib: ["ES2022"],
+        module: "NodeNext",
+        moduleResolution: "NodeNext",
+        strict: true,
+        skipLibCheck: true,
+        declaration: true,
+        sourceMap: true,
+        outDir: "dist",
+        rootDir: "src",
+        esModuleInterop: true,
+        isolatedModules: true,
+        verbatimModuleSyntax: true,
+    },
+    include: ["src/**/*.ts"],
+    exclude: ["node_modules", "dist"],
+}, null, 2) + "\n");
+writeFileSync(join(dir, "esbuild.config.mjs"), `import { build } from "esbuild";
+
+await build({
+  entryPoints: ["src/index.ts"],
+  bundle: true,
+  platform: "node",
+  target: "node20",
+  format: "esm",
+  outfile: "dist/index.mjs",
+  sourcemap: true,
+  external: [],
+  banner: { js: 'import{createRequire}from"module";const require=createRequire(import.meta.url);' },
+});
+
+console.log("Built handler");
+`);
+writeFileSync(join(dir, "src/index.ts"), `import { createHandler, type HandlerInput, type HandlerOutcome } from "@ruvos/handler-sdk";
+
+async function handle(input: HandlerInput): Promise<HandlerOutcome> {
+  // Access input.payload.resources for FHIR resources,
+  // input.config for per-registration configuration,
+  // and input.stage for the pipeline stage.
+  // Return passthrough, transform, route_to, requeue, or fail.
+
+  return { action: "passthrough" };
+}
+
+export const handler = createHandler({ handlerId: "${slug}" }, handle);
+`);
+writeFileSync(join(dir, "infra/main.tf"), `module "handler" {
+  source = "git::https://gitlab.com/ruvos/ruvos-platform/ruvos-io.git//infra/modules/tenant-handler"
+
+  environment        = var.environment
+  handler_slug       = "${slug}"
+  payload_bucket_arn = var.payload_bucket_arn
+  memory_size        = 256
+  timeout            = 60
+}
+
+output "lambda_arn" {
+  value = module.handler.function_arn
+}
+
+output "function_name" {
+  value = module.handler.function_name
+}
+`);
+writeFileSync(join(dir, "infra/variables.tf"), `variable "environment" {
+  type    = string
+  default = "dev"
+}
+
+variable "payload_bucket_arn" {
+  type        = string
+  description = "ARN of the Ruvos payloads S3 bucket"
+}
+`);
+writeFileSync(join(dir, ".gitlab-ci.yml"), `stages:
+  - build
+  - deploy
+  - register
+
+variables:
+  AWS_DEFAULT_REGION: us-east-1
+  NODE_VERSION: "20"
+
+.aws_oidc_setup: &aws_oidc_setup
+  id_tokens:
+    GITLAB_OIDC_TOKEN:
+      aud: https://gitlab.com
+  before_script:
+    - export AWS_ROLE_ARN="\${AWS_GITLAB_ROLE_ARN}"
+    - export AWS_ROLE_SESSION_NAME="gitlab-\${CI_PROJECT_PATH_SLUG}-\${CI_PIPELINE_ID}"
+    - export AWS_WEB_IDENTITY_TOKEN_FILE="\${CI_PROJECT_DIR}/.gitlab-oidc-jwt"
+    - printf '%s' "\${GITLAB_OIDC_TOKEN}" > "\${AWS_WEB_IDENTITY_TOKEN_FILE}"
+
+build:
+  stage: build
+  image: node:\${NODE_VERSION}
+  script:
+    - corepack enable
+    - pnpm install --frozen-lockfile
+    - pnpm build
+    - cd dist && zip -r handler.zip index.mjs index.mjs.map
+  artifacts:
+    paths:
+      - dist/handler.zip
+    expire_in: 1 day
+
+deploy:
+  stage: deploy
+  image:
+    name: amazon/aws-cli:latest
+    entrypoint: [""]
+  <<: *aws_oidc_setup
+  needs:
+    - job: build
+      artifacts: true
+  script:
+    - aws lambda update-function-code
+        --function-name ruvos-\${ENV:-dev}-handler-${slug}
+        --zip-file fileb://dist/handler.zip
+  rules:
+    - if: $AWS_GITLAB_ROLE_ARN && $CI_COMMIT_BRANCH == "main"
+
+register:
+  stage: register
+  image: curlimages/curl:latest
+  needs:
+    - job: deploy
+  script:
+    - |
+      curl -sf -X PUT "\${RUVOS_API_URL}/v1/platform/handlers/${slug}" \\
+        -H "Authorization: Bearer \${RUVOS_OPERATOR_TOKEN}" \\
+        -H "Content-Type: application/json" \\
+        -d '{
+          "displayName": "Handler: ${slug}",
+          "lambdaArn": "'\${HANDLER_LAMBDA_ARN}'",
+          "supportedStages": ["post_downstream_fetch", "pre_store"],
+          "defaultTimeoutMs": 60000,
+          "version": "0.1.0"
+        }'
+  rules:
+    - if: $AWS_GITLAB_ROLE_ARN && $CI_COMMIT_BRANCH == "main"
+`);
+writeFileSync(join(dir, "README.md"), `# ruvos-handler-${slug}
+
+Custom pipeline handler for the Ruvos platform.
+
+## Development
+
+\`\`\`bash
+pnpm install
+pnpm build
+\`\`\`
+
+## Deployment
+
+Push to \`main\` triggers the GitLab CI pipeline which:
+1. Builds the handler
+2. Deploys to AWS Lambda
+3. Registers with the Ruvos platform
+
+## Handler Interface
+
+The handler receives a \`HandlerInput\` and must return a \`HandlerOutcome\`:
+
+- \`passthrough\` — continue normal pipeline
+- \`transform\` — replace resources with your modified version
+- \`route_to\` — forward payload to a URL, skip normal storage
+- \`requeue\` — retry later with optional delay
+- \`fail\` — abort the job with a reason
+`);
+writeFileSync(join(dir, ".gitignore"), `node_modules/
+dist/
+.tsbuildinfo
+`);
+console.log(`Created handler scaffold at: ${dir}`);
+console.log("");
+console.log("Next steps:");
+console.log(`  cd ruvos-handler-${slug}`);
+console.log("  pnpm install");
+console.log("  # Edit src/index.ts with your handler logic");
+console.log("  pnpm build");
+//# sourceMappingURL=create-handler.js.map

package/dist/cli/create-handler.js.map

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

package/dist/create-handler.d.ts

@@ -0,0 +1,7 @@
+import type { HandlerInput, HandlerOutcome, HandlerFunction } from "./types.js";
+export interface CreateHandlerOptions {
+    handlerId: string;
+    timeoutMs?: number;
+}
+export declare function createHandler(options: CreateHandlerOptions, fn: HandlerFunction): (event: HandlerInput) => Promise<HandlerOutcome>;
+//# sourceMappingURL=create-handler.d.ts.map

package/dist/create-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-handler.d.ts","sourceRoot":"","sources":["../src/create-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIhF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,eAAe,GAClB,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,cAAc,CAAC,CA4ClD"}

package/dist/create-handler.js

@@ -0,0 +1,40 @@
+import { validateOutcome } from "./validate.js";
+import { createHandlerLogger } from "./logger.js";
+export function createHandler(options, fn) {
+    return async (event) => {
+        const logger = createHandlerLogger({
+            handlerId: options.handlerId,
+            correlationId: event.correlationId,
+            tenantId: event.tenantId,
+            stage: event.stage,
+        });
+        const startTime = Date.now();
+        logger.info("handler_invoked", {
+            jobId: event.jobId,
+            connectorType: event.connectorType,
+            resourceCount: event.payload.resources?.length,
+        });
+        try {
+            const timeoutMs = options.timeoutMs ?? 120_000;
+            const result = await Promise.race([
+                fn(event),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Handler timed out after ${timeoutMs}ms`)), timeoutMs)),
+            ]);
+            const validated = validateOutcome(result);
+            const durationMs = Date.now() - startTime;
+            logger.info("handler_completed", {
+                action: validated.action,
+                durationMs,
+                ...(validated.action === "transform" ? { outputResourceCount: validated.resources.length } : {}),
+            });
+            return validated;
+        }
+        catch (err) {
+            const durationMs = Date.now() - startTime;
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error("handler_error", { error: reason, durationMs });
+            return { action: "fail", reason };
+        }
+    };
+}
+//# sourceMappingURL=create-handler.js.map

package/dist/create-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-handler.js","sourceRoot":"","sources":["../src/create-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOlD,MAAM,UAAU,aAAa,CAC3B,OAA6B,EAC7B,EAAmB;IAEnB,OAAO,KAAK,EAAE,KAAmB,EAA2B,EAAE;QAC5D,MAAM,MAAM,GAAG,mBAAmB,CAAC;YACjC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;YAC7B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM;SAC/C,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;YAC/C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBAChC,EAAE,CAAC,KAAK,CAAC;gBACT,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,SAAS,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CACzF;aACF,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;YAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAE1C,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE;gBAC/B,MAAM,EAAE,SAAS,CAAC,MAAM;gBACxB,UAAU;gBACV,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjG,CAAC,CAAC;YAEH,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAEhE,MAAM,CAAC,KAAK,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;YAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACpC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { HookStage, FHIRResource, HandlerInput, HandlerOutcome, HandlerFunction, PlatformHandler, TenantHandler, HandlerScope, HookRegistration, } from "./types.js";
+export { validateOutcome, HandlerValidationError } from "./validate.js";
+export { createHandler, type CreateHandlerOptions } from "./create-handler.js";
+export { createHandlerLogger, type HandlerLogger } from "./logger.js";
+export { parseCcda } from "./ccda.js";
+//# 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,YAAY,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,YAAY,EACZ,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { validateOutcome, HandlerValidationError } from "./validate.js";
+export { createHandler } from "./create-handler.js";
+export { createHandlerLogger } from "./logger.js";
+export { parseCcda } from "./ccda.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAsB,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,12 @@
+export interface HandlerLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export declare function createHandlerLogger(context: {
+    handlerId: string;
+    correlationId: string;
+    tenantId: string;
+    stage: string;
+}): HandlerLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,CA8BhB"}

package/dist/logger.js

@@ -0,0 +1,32 @@
+export function createHandlerLogger(context) {
+    const base = {
+        service: `handler:${context.handlerId}`,
+        correlationId: context.correlationId,
+        tenantId: context.tenantId,
+        stage: context.stage,
+    };
+    function log(level, message, data) {
+        const entry = JSON.stringify({
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            ...base,
+            ...data,
+        });
+        if (level === "error") {
+            console.error(entry);
+        }
+        else if (level === "warn") {
+            console.warn(entry);
+        }
+        else {
+            console.log(entry);
+        }
+    }
+    return {
+        info: (msg, data) => log("info", msg, data),
+        warn: (msg, data) => log("warn", msg, data),
+        error: (msg, data) => log("error", msg, data),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,mBAAmB,CAAC,OAKnC;IACC,MAAM,IAAI,GAAG;QACX,OAAO,EAAE,WAAW,OAAO,CAAC,SAAS,EAAE;QACvC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;IAEF,SAAS,GAAG,CAAC,KAAa,EAAE,OAAe,EAAE,IAA8B;QACzE,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;YAC3B,KAAK;YACL,OAAO;YACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,GAAG,IAAI;YACP,GAAG,IAAI;SACR,CAAC,CAAC;QACH,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;aAAM,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export type HookStage = "post_downstream_fetch" | "pre_store" | "post_store";
+export interface FHIRResource {
+    resourceType: string;
+    id?: string;
+    [key: string]: unknown;
+}
+export interface HandlerInput {
+    stage: HookStage;
+    tenantId: string;
+    jobId: string;
+    correlationId: string;
+    connectorType: string;
+    config?: Record<string, unknown>;
+    payload: {
+        resources?: FHIRResource[];
+        metadata?: Record<string, unknown>;
+        s3Key?: string;
+    };
+}
+export type HandlerOutcome = {
+    action: "passthrough";
+} | {
+    action: "transform";
+    resources: FHIRResource[];
+    metadata?: Record<string, unknown>;
+} | {
+    action: "route_to";
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body: unknown;
+} | {
+    action: "requeue";
+    delaySeconds?: number;
+} | {
+    action: "fail";
+    reason: string;
+};
+export type HandlerFunction = (input: HandlerInput) => Promise<HandlerOutcome>;
+export interface PlatformHandler {
+    id: string;
+    handlerId: string;
+    displayName: string;
+    description?: string;
+    type: "lambda";
+    lambdaArn: string;
+    supportedStages: HookStage[];
+    defaultTimeoutMs: number;
+    version: string;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TenantHandler {
+    id: string;
+    tenantId: string;
+    handlerId: string;
+    displayName: string;
+    type: "webhook" | "lambda";
+    webhookUrl?: string;
+    signingSecretArn?: string;
+    lambdaArn?: string;
+    enabled: boolean;
+    timeoutMs: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export type HandlerScope = "platform" | "tenant";
+export interface HookRegistration {
+    tenantId: string;
+    stage: HookStage;
+    handlerId: string;
+    handlerScope: HandlerScope;
+    priority: number;
+    enabled: boolean;
+    config?: Record<string, unknown>;
+}
+//# 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,2 @@
+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":""}

package/dist/validate.d.ts

@@ -0,0 +1,6 @@
+import type { HandlerOutcome } from "./types.js";
+export declare class HandlerValidationError extends Error {
+    constructor(message: string);
+}
+export declare function validateOutcome(value: unknown): HandlerOutcome;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAgE9D"}

package/dist/validate.js

@@ -0,0 +1,51 @@
+const VALID_ACTIONS = new Set(["passthrough", "transform", "route_to", "requeue", "fail"]);
+export class HandlerValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HandlerValidationError";
+    }
+}
+export function validateOutcome(value) {
+    if (!value || typeof value !== "object") {
+        throw new HandlerValidationError("Handler outcome must be a non-null object");
+    }
+    const obj = value;
+    const action = obj["action"];
+    if (typeof action !== "string" || !VALID_ACTIONS.has(action)) {
+        throw new HandlerValidationError(`Invalid handler outcome action: "${String(action)}". Must be one of: ${[...VALID_ACTIONS].join(", ")}`);
+    }
+    switch (action) {
+        case "passthrough":
+            break;
+        case "transform":
+            if (!Array.isArray(obj["resources"])) {
+                throw new HandlerValidationError('Handler outcome "transform" requires a "resources" array');
+            }
+            for (const r of obj["resources"]) {
+                if (!r || typeof r !== "object" || typeof r["resourceType"] !== "string") {
+                    throw new HandlerValidationError("Each resource in transform outcome must have a string resourceType");
+                }
+            }
+            break;
+        case "route_to":
+            if (typeof obj["url"] !== "string" || !obj["url"]) {
+                throw new HandlerValidationError('Handler outcome "route_to" requires a non-empty "url" string');
+            }
+            if (!String(obj["url"]).startsWith("https://")) {
+                throw new HandlerValidationError('Handler outcome "route_to" url must use HTTPS');
+            }
+            break;
+        case "requeue":
+            if (obj["delaySeconds"] !== undefined && typeof obj["delaySeconds"] !== "number") {
+                throw new HandlerValidationError('Handler outcome "requeue" delaySeconds must be a number');
+            }
+            break;
+        case "fail":
+            if (typeof obj["reason"] !== "string") {
+                throw new HandlerValidationError('Handler outcome "fail" requires a "reason" string');
+            }
+            break;
+    }
+    return value;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3F,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,sBAAsB,CAAC,2CAA2C,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,sBAAsB,CAC9B,oCAAoC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxG,CAAC;IACJ,CAAC;IAED,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,aAAa;YAChB,MAAM;QAER,KAAK,WAAW;YACd,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,sBAAsB,CAC9B,0DAA0D,CAC3D,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,CAAc,EAAE,CAAC;gBAC9C,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAA6B,CAAC,cAAc,CAAC,KAAK,QAAQ,EAAE,CAAC;oBACtG,MAAM,IAAI,sBAAsB,CAC9B,oEAAoE,CACrE,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,UAAU;YACb,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,sBAAsB,CAC9B,8DAA8D,CAC/D,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,sBAAsB,CAC9B,+CAA+C,CAChD,CAAC;YACJ,CAAC;YACD,MAAM;QAER,KAAK,SAAS;YACZ,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,cAAc,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACjF,MAAM,IAAI,sBAAsB,CAC9B,yDAAyD,CAC1D,CAAC;YACJ,CAAC;YACD,MAAM;QAER,KAAK,MAAM;YACT,IAAI,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACtC,MAAM,IAAI,sBAAsB,CAC9B,mDAAmD,CACpD,CAAC;YACJ,CAAC;YACD,MAAM;IACV,CAAC;IAED,OAAO,KAAuB,CAAC;AACjC,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ruvos/handler-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "!dist/.tsbuildinfo"],
+  "description": "SDK for building custom pipeline handlers for the Ruvos healthcare data exchange platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/ruvos/ruvos-platform/ruvos-io.git",
+    "directory": "packages/handler-sdk"
+  },
+  "keywords": ["ruvos", "healthcare", "fhir", "handler", "pipeline", "sdk"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2"
+  },
+  "bin": {
+    "create-handler": "./dist/cli/create-handler.js"
+  }
+}