@layer-drone/protocol 0.6.0 → 0.7.0

package/README.md

@@ -1,43 +1,114 @@
-# Protocol SDK Test Setup
+# LayerDrone Protocol SDK
 
-This directory contains comprehensive tests for the Layer Drone Protocol SDK that validate SDK functionality using mocks and simulated API responses.
+Published as [`@layer-drone/protocol`](https://www.npmjs.com/package/@layer-drone/protocol).
 
-## Test Configuration
+## Description
 
-The tests are designed to be completely self-contained and run seamlessly in CI/CD environments without any external dependencies. All API interactions are mocked to ensure reliable, fast test execution.
+This SDK provides a typed client for using LayerDrone's REST API and parsing webhook events.
 
-## Running Tests
+## Philosophy
 
-### Standard Test Run
-```bash
-# Run all tests with mocks
-pnpm test
+The LayerDrone protocol exists as a hybrid of on and off-chain functionality. This helps strike
+the right balance of transparency, speed, and familiarity.
+
+- Objects related to missions & reward entitlement are recorded on-chain
+- Off-chain indexing supports non-critical data outside of smart contracts, keeping gas usage low
+- A REST API and webhook broadcaster offer a familiar facade over aggregated on & off-chain data
+
+## Installation
+
+```sh
+$ npm install @layer-drone/protocol
 ```
 
-### With Coverage
-```bash
-# Run tests with coverage reporting
-pnpm test:coverage
+## Usage
+
+### Getting an API key
+
+Organizations and API keys are provisioned manually for private use only at the moment.
+
+### Making API calls
+
+```ts
+import * as LayerDrone from "@layer-drone/protocol";
+
+const client = LayerDrone.createClient({
+  baseUrl: env.PROTOCOL_API_URL,
+  auth: env.PROTOCOL_API_KEY,
+});
+
+// Submit a flight for validation
+const response = await LayerDrone.flightsControllerValidateFlight({
+  client,
+  body: {
+    storageKey: "s3://layerdrone-flights-staging/12345",
+    pilotAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
+    missionId: 123n,
+    flightTimestamp: "2023-10-15T14:25:30.123Z",
+    flightRequestInfo: {
+      flightPlanId: 2,
+      filePaths: [
+        "images/IMG_0001.JPG",
+        "images/IMG_0002.JPG",
+        "images/IMG_0003.JPG",
+      ],
+      zoneHash: "https://explorer.spexi.com/zone/8928de8de43ffff",
+      provenancePath: "provenance.json",
+    },
+  },
+});
 ```
 
-## Test Coverage
+### Registering webhooks
+
+The SDK supports registering webhooks via the API.
 
-The test suite includes:
+```ts
+import * as LayerDrone from "@layer-drone/protocol";
 
-1. **Client Creation and Configuration** - SDK initialization and configuration
-2. **API Integration Tests** - Tests using mocked API responses:
-   - Health check endpoint (`/`)
-   - Sun altitude calculations (`/conditions/sun-altitude`)
-   - Event schema retrieval (`/schema/event`)
-3. **Error Handling** - Network errors, 404s, invalid parameters
-4. **Response Styles** - Data-only vs full response formats
-5. **Event Parsing** - Webhook event validation and parsing
-6. **Integration Tests** - Complete workflows using mocks:
-   - Flight workflow (storage key generation, presigned URLs, validation)
-   - API token management (CRUD operations)
-   - Mission creation workflow
-7. **Type Safety** - TypeScript type validation and BigInt handling
+const client = LayerDrone.createClient({
+  baseUrl: process.env.PROTOCOL_API_URL!,
+  auth: process.env.PROTOCOL_API_KEY!,
+});
 
-## SonarQube Integration
+const webhook = await LayerDrone.webhooksControllerCreate({
+  client,
+  path: { org_id: 1 },
+  body: {
+    name: "MyOrg Webhook",
+    url: "https://api.example.com/webhooks/layer-drone",
+    event_types: ["protocol.flight.reviewed"],
+    active: true,
+  },
+});
 
-Test coverage is automatically included in SonarQube scans via the LCOV report at `./coverage/lcov.info`.
+// `webhook.id` is the config id. `webhook.secret` is the value LayerDrone
+// will send on each request as the X-Webhook-Secret header.
+```
+
+### Receiving webhook events
+
+Your API can parse webhook payloads at a registered endpoint.
+
+```ts
+import type { Request, Response } from "express";
+
+import { parseWebhookEvent } from "@layer-drone/protocol";
+
+class MyController {
+  async handleLayerDroneWebhookEvent(req: Request, res: Response) {
+    const event = parseWebhookEvent(req, process.env.LAYERDRONE_WEBHOOK_SECRET);
+
+    let message = "Event received";
+    switch (event.event_type) {
+      case "protocol.flight.reviewed":
+        // handle narrowed event type
+        break;
+      default:
+        message = `Handler for ${event.event_type} not implemented`;
+    }
+
+    res.status(200).send({ message });
+  }
+}
+```

package/dist/index.js

@@ -882,9 +882,13 @@ var getMissionResponseDtoSchemaResponseTransformer = /* @__PURE__ */ __name((dat
   data.captureEndTime = new Date(data.captureEndTime);
   data.createdAt = new Date(data.createdAt);
   data.updatedAt = new Date(data.updatedAt);
-  data.payout.createdAt = new Date(data.payout.createdAt);
-  data.vault.createdAt = new Date(data.vault.createdAt);
-  data.vault.updatedAt = new Date(data.vault.updatedAt);
+  if (data.payout) {
+    data.payout.createdAt = new Date(data.payout.createdAt);
+  }
+  if (data.vault) {
+    data.vault.createdAt = new Date(data.vault.createdAt);
+    data.vault.updatedAt = new Date(data.vault.updatedAt);
+  }
   return data;
 }, "getMissionResponseDtoSchemaResponseTransformer");
 var missionsControllerGetMissionResponseTransformer = /* @__PURE__ */ __name(async (data) => {
@@ -897,9 +901,13 @@ var getMissionsResponseDtoSchemaResponseTransformer = /* @__PURE__ */ __name((da
     item.captureEndTime = new Date(item.captureEndTime);
     item.createdAt = new Date(item.createdAt);
     item.updatedAt = new Date(item.updatedAt);
-    item.payout.createdAt = new Date(item.payout.createdAt);
-    item.vault.createdAt = new Date(item.vault.createdAt);
-    item.vault.updatedAt = new Date(item.vault.updatedAt);
+    if (item.payout) {
+      item.payout.createdAt = new Date(item.payout.createdAt);
+    }
+    if (item.vault) {
+      item.vault.createdAt = new Date(item.vault.createdAt);
+      item.vault.updatedAt = new Date(item.vault.updatedAt);
+    }
     return item;
   });
   return data;

package/dist/index.mjs

@@ -795,9 +795,13 @@ var getMissionResponseDtoSchemaResponseTransformer = /* @__PURE__ */ __name((dat
   data.captureEndTime = new Date(data.captureEndTime);
   data.createdAt = new Date(data.createdAt);
   data.updatedAt = new Date(data.updatedAt);
-  data.payout.createdAt = new Date(data.payout.createdAt);
-  data.vault.createdAt = new Date(data.vault.createdAt);
-  data.vault.updatedAt = new Date(data.vault.updatedAt);
+  if (data.payout) {
+    data.payout.createdAt = new Date(data.payout.createdAt);
+  }
+  if (data.vault) {
+    data.vault.createdAt = new Date(data.vault.createdAt);
+    data.vault.updatedAt = new Date(data.vault.updatedAt);
+  }
   return data;
 }, "getMissionResponseDtoSchemaResponseTransformer");
 var missionsControllerGetMissionResponseTransformer = /* @__PURE__ */ __name(async (data) => {
@@ -810,9 +814,13 @@ var getMissionsResponseDtoSchemaResponseTransformer = /* @__PURE__ */ __name((da
     item.captureEndTime = new Date(item.captureEndTime);
     item.createdAt = new Date(item.createdAt);
     item.updatedAt = new Date(item.updatedAt);
-    item.payout.createdAt = new Date(item.payout.createdAt);
-    item.vault.createdAt = new Date(item.vault.createdAt);
-    item.vault.updatedAt = new Date(item.vault.updatedAt);
+    if (item.payout) {
+      item.payout.createdAt = new Date(item.payout.createdAt);
+    }
+    if (item.vault) {
+      item.vault.createdAt = new Date(item.vault.createdAt);
+      item.vault.updatedAt = new Date(item.vault.updatedAt);
+    }
     return item;
   });
   return data;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@layer-drone/protocol",
   "description": "Layer Drone protocol SDK with typed API client and event parsing",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "MIT",
   "files": [
     "dist",

package/src/client/transformers.gen.ts

@@ -178,9 +178,13 @@ const getMissionResponseDtoSchemaResponseTransformer = (data: any) => {
   data.captureEndTime = new Date(data.captureEndTime);
   data.createdAt = new Date(data.createdAt);
   data.updatedAt = new Date(data.updatedAt);
-  data.payout.createdAt = new Date(data.payout.createdAt);
-  data.vault.createdAt = new Date(data.vault.createdAt);
-  data.vault.updatedAt = new Date(data.vault.updatedAt);
+  if (data.payout) {
+    data.payout.createdAt = new Date(data.payout.createdAt);
+  }
+  if (data.vault) {
+    data.vault.createdAt = new Date(data.vault.createdAt);
+    data.vault.updatedAt = new Date(data.vault.updatedAt);
+  }
   return data;
 };
 
@@ -197,9 +201,13 @@ const getMissionsResponseDtoSchemaResponseTransformer = (data: any) => {
     item.captureEndTime = new Date(item.captureEndTime);
     item.createdAt = new Date(item.createdAt);
     item.updatedAt = new Date(item.updatedAt);
-    item.payout.createdAt = new Date(item.payout.createdAt);
-    item.vault.createdAt = new Date(item.vault.createdAt);
-    item.vault.updatedAt = new Date(item.vault.updatedAt);
+    if (item.payout) {
+      item.payout.createdAt = new Date(item.payout.createdAt);
+    }
+    if (item.vault) {
+      item.vault.createdAt = new Date(item.vault.createdAt);
+      item.vault.updatedAt = new Date(item.vault.updatedAt);
+    }
     return item;
   });
   return data;