@fhirust/sdk 0.3.1 → 0.3.3

package/README.md

@@ -18,6 +18,7 @@ npm install @fhirust/sdk @bytecodealliance/componentize-js
 **Requirements:**
 - Node.js 18+ or Bun
 - TypeScript 5.0+
+- `@bytecodealliance/componentize-js` >= 0.14.0 (0.19+ recommended for security fixes)
 
 ---
 
@@ -33,14 +34,16 @@ const plugin = new FhirPlugin("my-validator", "1.0.0");
 
 // Validate Patient before creation
 plugin.beforeCreate<Patient>("Patient", (patient, ctx) => {
-  if (!patient.name || patient.name.length === 0) {
-    return reject("Patient must have at least one name");
-  }
-  return patient;
+    if (!patient.name || patient.name.length === 0) {
+        return reject("Patient must have at least one name");
+    }
+    return patient;
 });
 
 // Export plugin hooks
-export const { getMetadata, executeHook } = plugin.exports();
+const pluginExports = plugin.exports();
+export const lifecycle = pluginExports.lifecycle;
+export const hooks = pluginExports.hooks;
 ```
 
 ### 2. Build the plugin
@@ -130,16 +133,16 @@ return outcome([
 
 ### FHIR Client
 
-Access the FHIR server from within your plugin.
+Access the FHIR server from within your plugin using `plugin.fhir`.
 
 ```typescript
 plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
   // Search for duplicates
-  const bundle = await ctx.fhir.search("Patient", {
+  const bundle = await plugin.fhir.search("Patient", {
     identifier: patient.identifier?.[0]?.value
   });
 
-  if (bundle.total > 0) {
+  if (bundle.total && bundle.total > 0) {
     return reject("Duplicate patient identifier");
   }
 
@@ -148,20 +151,20 @@ plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
 ```
 
 **Methods:**
-- `fhir.search(resourceType, params)` — Search for resources
-- `fhir.read(resourceType, id)` — Read a resource by ID
-- `fhir.create(resourceType, resource)` — Create a new resource
-- `fhir.update(resourceType, id, resource)` — Update a resource
-- `fhir.delete(resourceType, id)` — Delete a resource
+- `plugin.fhir.search(resourceType, params)` — Search for resources
+- `plugin.fhir.read(resourceType, id)` — Read a resource by ID
+- `plugin.fhir.create(resourceType, resource)` — Create a new resource
+- `plugin.fhir.update(resourceType, id, resource)` — Update a resource
+- `plugin.fhir.delete(resourceType, id)` — Delete a resource
 
 ### HTTP Client
 
-Make HTTP requests to external APIs (requires `http.fetch` permission).
+Make HTTP requests to external APIs using `plugin.http` (requires `http.fetch` permission).
 
 ```typescript
 plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
   // Verify insurance eligibility via external API
-  const response = await ctx.http.post("https://api.insurance.com/verify", {
+  const response = await plugin.http.post("https://api.insurance.com/verify", {
     body: { memberId: patient.identifier?.[0]?.value }
   });
 
@@ -175,11 +178,11 @@ plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
 
 ### Event Emitter
 
-Emit events for async processing.
+Emit events for async processing using `plugin.events`.
 
 ```typescript
 plugin.afterCreate<Patient>("Patient", (patient, ctx) => {
-  ctx.events.emit("patient.created", {
+  plugin.events.emit("patient.created", {
     id: patient.id,
     name: patient.name?.[0]?.family
   });
@@ -190,18 +193,20 @@ plugin.afterCreate<Patient>("Patient", (patient, ctx) => {
 
 ### Logger
 
-Structured logging with severity levels.
+Structured logging with severity levels using `plugin.log`.
 
 ```typescript
 plugin.beforeCreate<Patient>("Patient", (patient, ctx) => {
-  ctx.logger.info("Validating patient", { id: patient.id });
-  ctx.logger.warn("Missing phone number", { id: patient.id });
-  ctx.logger.error("Validation failed", { id: patient.id });
+  plugin.log.info(`Validating patient: ${patient.id}`);
+  plugin.log.warn(`Missing phone number for patient: ${patient.id}`);
+  plugin.log.error(`Validation failed for patient: ${patient.id}`);
 
   return patient;
 });
 ```
 
+**Note:** Logger methods accept only string messages. To include structured data, serialize it in the message string using template literals or `JSON.stringify()`.
+
 ---
 
 ## 💡 Examples
@@ -227,7 +232,7 @@ plugin.beforeCreate<Patient>("Patient", (patient) => {
   return patient;
 });
 
-export const { getMetadata, executeHook } = plugin.exports();
+export const { lifecycle, hooks } = plugin.exports();
 ```
 
 ### Example 2: Auto-Tag Resources
@@ -251,7 +256,7 @@ plugin.beforeCreate<Patient>("Patient", (patient) => {
   return patient;
 });
 
-export const { getMetadata, executeHook } = plugin.exports();
+export const { lifecycle, hooks } = plugin.exports();
 ```
 
 ### Example 3: Duplicate Detection
@@ -266,19 +271,25 @@ plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
   const identifier = patient.identifier?.[0]?.value;
   if (!identifier) return patient;
 
-  // Search for existing patients with same identifier
-  const bundle = await ctx.fhir.search("Patient", {
-    identifier: identifier
-  });
+  try {
+    // Search for existing patients with same identifier
+    const bundle = await plugin.fhir.search("Patient", {
+      identifier: identifier
+    });
 
-  if (bundle.total && bundle.total > 0) {
-    return reject(`Duplicate patient found with identifier: ${identifier}`);
-  }
+    if (bundle.total && bundle.total > 0) {
+      return reject(`Duplicate patient found with identifier: ${identifier}`);
+    }
 
-  return patient;
+    return patient;
+  } catch (error) {
+    plugin.log.error(`Duplicate check failed: ${error}`);
+    // Fail open: allow creation if duplicate check fails
+    return patient;
+  }
 });
 
-export const { getMetadata, executeHook } = plugin.exports();
+export const { lifecycle, hooks } = plugin.exports();
 ```
 
 ### Example 4: External API Integration
@@ -295,23 +306,28 @@ plugin.beforeCreate<Patient>("Patient", async (patient, ctx) => {
   )?.value;
 
   if (memberId) {
-    // Verify with external insurance API
-    const response = await ctx.http.post(
-      "https://api.insurance.com/verify",
-      { body: { memberId } }
-    );
-
-    if (!response.ok) {
-      return reject("Insurance verification failed");
+    try {
+      // Verify with external insurance API
+      const response = await plugin.http.post(
+        "https://api.insurance.com/verify",
+        { body: { memberId } }
+      );
+
+      if (!response.ok) {
+        return reject("Insurance verification failed");
+      }
+
+      plugin.log.info(`Insurance verified for member: ${memberId}`);
+    } catch (error) {
+      plugin.log.error(`Insurance verification error: ${error}`);
+      return reject("Insurance verification service unavailable");
     }
-
-    ctx.logger.info("Insurance verified", { memberId });
   }
 
   return patient;
 });
 
-export const { getMetadata, executeHook } = plugin.exports();
+export const { lifecycle, hooks } = plugin.exports();
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fhirust/sdk",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "TypeScript SDK for building FHIRust WASM plugins",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,7 +43,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@bytecodealliance/componentize-js": ">=0.14.0"
+    "@bytecodealliance/componentize-js": ">=0.14.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@bytecodealliance/componentize-js": {
@@ -51,9 +51,9 @@
     }
   },
   "devDependencies": {
-    "@bytecodealliance/componentize-js": "^0.14.0",
+    "@bytecodealliance/componentize-js": "^0.19.3",
     "@types/node": "^25.2.2",
     "tsx": "^4.21.0",
     "typescript": "^5.5.0"
   }
-}
+}