@forwardimpact/librpc 0.1.109 → 0.1.111

package/README.md

@@ -12,3 +12,12 @@ transport.
 ```js
 import { Server, Client, createClient, createTracer } from '@forwardimpact/librpc';
 ```
+
+## Documentation
+
+- [Ship a Service Endpoint](https://www.forwardimpact.team/docs/libraries/typed-contracts/ship-endpoint/index.md)
+  — ship and consume a gRPC service with typed contracts, authentication,
+  retries, and health checks; `fit-unary` is the command-line client for it.
+- [Keep Types Synced with Proto Definitions](https://www.forwardimpact.team/docs/libraries/typed-contracts/index.md)
+  — the full workflow for defining proto contracts and generating typed base
+  classes and clients.

package/bin/fit-unary.js

@@ -18,6 +18,20 @@ const definition = {
     json: { type: "boolean", description: "Output help as JSON" },
   },
   examples: ['fit-unary memory GetWindow \'{"resource_id":"..."}\''],
+  documentation: [
+    {
+      title: "Ship a Service Endpoint",
+      url: "https://www.forwardimpact.team/docs/libraries/typed-contracts/ship-endpoint/index.md",
+      description:
+        "Ship and consume a gRPC service with typed contracts, authentication, retries, and health checks; fit-unary is the command-line client for it.",
+    },
+    {
+      title: "Keep Types Synced with Proto Definitions",
+      url: "https://www.forwardimpact.team/docs/libraries/typed-contracts/index.md",
+      description:
+        "The full workflow for defining proto contracts and generating typed base classes and clients.",
+    },
+  ],
 };
 
 const cli = createCli(definition, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/librpc",
-  "version": "0.1.109",
+  "version": "0.1.111",
   "description": "gRPC server and client framework — ship service endpoints without reimplementing transport.",
   "keywords": [
     "grpc",

package/src/generated/definitions/exports.js

@@ -9,8 +9,8 @@ export { GhuserServiceDefinition } from "./ghuser.js";
 export { GraphServiceDefinition } from "./graph.js";
 export { MapServiceDefinition } from "./map.js";
 export { PathwayServiceDefinition } from "./pathway.js";
+export { SpanServiceDefinition } from "./span.js";
 export { TenancyServiceDefinition } from "./tenancy.js";
-export { TraceServiceDefinition } from "./trace.js";
 export { VectorServiceDefinition } from "./vector.js";
 
 // Import service definitions to make them available for aggregation
@@ -21,8 +21,8 @@ import { GhuserServiceDefinition } from "./ghuser.js";
 import { GraphServiceDefinition } from "./graph.js";
 import { MapServiceDefinition } from "./map.js";
 import { PathwayServiceDefinition } from "./pathway.js";
+import { SpanServiceDefinition } from "./span.js";
 import { TenancyServiceDefinition } from "./tenancy.js";
-import { TraceServiceDefinition } from "./trace.js";
 import { VectorServiceDefinition } from "./vector.js";
 
 // Aggregate exports for convenience
@@ -34,8 +34,8 @@ export const definitions = {
   graph: GraphServiceDefinition,
   map: MapServiceDefinition,
   pathway: PathwayServiceDefinition,
+  span: SpanServiceDefinition,
   tenancy: TenancyServiceDefinition,
-  trace: TraceServiceDefinition,
   vector: VectorServiceDefinition,
 };
 

package/src/generated/definitions/span.js

@@ -0,0 +1,50 @@
+import { span } from "@forwardimpact/libtype";
+
+/**
+ * Pre-compiled gRPC service definition for Span
+ * Generated at build time
+ */
+export const SpanServiceDefinition = {
+  RecordSpan: {
+    path: '/span.Span/RecordSpan',
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => {
+      return Buffer.from(span.SpanItem.encode(value).finish());
+    },
+    requestDeserialize: (value) => {
+      return span.SpanItem.toObject(
+        span.SpanItem.decode(value)
+      );
+    },
+    responseSerialize: (value) => {
+      return Buffer.from(span.RecordResponse.encode(value).finish());
+    },
+    responseDeserialize: (value) => {
+      return span.RecordResponse.toObject(
+        span.RecordResponse.decode(value)
+      );
+    },
+  },
+  QuerySpans: {
+    path: '/span.Span/QuerySpans',
+    requestStream: false,
+    responseStream: false,
+    requestSerialize: (value) => {
+      return Buffer.from(span.QueryRequest.encode(value).finish());
+    },
+    requestDeserialize: (value) => {
+      return span.QueryRequest.toObject(
+        span.QueryRequest.decode(value)
+      );
+    },
+    responseSerialize: (value) => {
+      return Buffer.from(span.QueryResponse.encode(value).finish());
+    },
+    responseDeserialize: (value) => {
+      return span.QueryResponse.toObject(
+        span.QueryResponse.decode(value)
+      );
+    },
+  },
+};

package/src/generated/services/exports.js

@@ -9,8 +9,8 @@ export { GhuserBase } from "./ghuser/service.js";
 export { GraphBase } from "./graph/service.js";
 export { MapBase } from "./map/service.js";
 export { PathwayBase } from "./pathway/service.js";
+export { SpanBase } from "./span/service.js";
 export { TenancyBase } from "./tenancy/service.js";
-export { TraceBase } from "./trace/service.js";
 export { VectorBase } from "./vector/service.js";
 
 // Client Classes
@@ -21,8 +21,8 @@ export { GhuserClient } from "./ghuser/client.js";
 export { GraphClient } from "./graph/client.js";
 export { MapClient } from "./map/client.js";
 export { PathwayClient } from "./pathway/client.js";
+export { SpanClient } from "./span/client.js";
 export { TenancyClient } from "./tenancy/client.js";
-export { TraceClient } from "./trace/client.js";
 export { VectorClient } from "./vector/client.js";
 
 // Import service base classes to make them available for aggregation
@@ -33,8 +33,8 @@ import { GhuserBase } from "./ghuser/service.js";
 import { GraphBase } from "./graph/service.js";
 import { MapBase } from "./map/service.js";
 import { PathwayBase } from "./pathway/service.js";
+import { SpanBase } from "./span/service.js";
 import { TenancyBase } from "./tenancy/service.js";
-import { TraceBase } from "./trace/service.js";
 import { VectorBase } from "./vector/service.js";
 
 // Import client classes to make them available for aggregation
@@ -45,8 +45,8 @@ import { GhuserClient } from "./ghuser/client.js";
 import { GraphClient } from "./graph/client.js";
 import { MapClient } from "./map/client.js";
 import { PathwayClient } from "./pathway/client.js";
+import { SpanClient } from "./span/client.js";
 import { TenancyClient } from "./tenancy/client.js";
-import { TraceClient } from "./trace/client.js";
 import { VectorClient } from "./vector/client.js";
 
 // Aggregate exports for convenience
@@ -58,8 +58,8 @@ export const services = {
   GraphBase,
   MapBase,
   PathwayBase,
+  SpanBase,
   TenancyBase,
-  TraceBase,
   VectorBase,
 };
 
@@ -71,8 +71,8 @@ export const clients = {
   GraphClient,
   MapClient,
   PathwayClient,
+  SpanClient,
   TenancyClient,
-  TraceClient,
   VectorClient,
 };
 
@@ -87,8 +87,8 @@ export default {
   GraphBase,
   MapBase,
   PathwayBase,
+  SpanBase,
   TenancyBase,
-  TraceBase,
   VectorBase,
   BridgeClient,
   EmbeddingClient,
@@ -97,7 +97,7 @@ export default {
   GraphClient,
   MapClient,
   PathwayClient,
+  SpanClient,
   TenancyClient,
-  TraceClient,
   VectorClient,
 };

package/src/generated/services/{trace → span}/client.js

@@ -3,15 +3,15 @@
 import { Client } from "@forwardimpact/librpc/client.js";
 import { createAuth, createGrpc } from "@forwardimpact/librpc/base.js";
 import { createObserver } from "@forwardimpact/libtelemetry";
-import { trace } from "@forwardimpact/libtype";
+import { span } from "@forwardimpact/libtype";
 
 /**
- * Typed client for the Trace gRPC service.
+ * Typed client for the Span gRPC service.
  * Extends the `Client` class for shared gRPC client functionality.
  */
-export class TraceClient extends Client {
+export class SpanClient extends Client {
   /**
-   * Creates a new Trace client instance
+   * Creates a new Span client instance
    * @param {object} config - Service configuration
    * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Injected runtime bag (required; the default auth factory reads SERVICE_SECRET from it)
    * @param {import("@forwardimpact/libtelemetry").Logger} [logger] - Optional logger instance
@@ -24,35 +24,35 @@ export class TraceClient extends Client {
 
   /**
    * Call the `RecordSpan` RPC with request/response type conversion.
-   * @param { trace.Span } req - Typed request message.
-   * @returns { Promise<trace.RecordResponse> } Typed response message.
+   * @param { span.SpanItem } req - Typed request message.
+   * @returns { Promise<span.RecordResponse> } Typed response message.
    */
   async RecordSpan(req) {
     // Accept a typed message or a plain init object (coerced to the typed type).
     const message =
-      req instanceof trace.Span
+      req instanceof span.SpanItem
         ? req
-        : new trace.Span(req);
-    const request = trace.Span.toObject(message);
+        : new span.SpanItem(req);
+    const request = span.SpanItem.toObject(message);
     
     // Make gRPC call (tracing handled by base Client class)
-    return this.callUnary("RecordSpan", request, (res) => trace.RecordResponse.fromObject(res));
+    return this.callUnary("RecordSpan", request, (res) => span.RecordResponse.fromObject(res));
   }
 
   /**
    * Call the `QuerySpans` RPC with request/response type conversion.
-   * @param { trace.QueryRequest } req - Typed request message.
-   * @returns { Promise<trace.QueryResponse> } Typed response message.
+   * @param { span.QueryRequest } req - Typed request message.
+   * @returns { Promise<span.QueryResponse> } Typed response message.
    */
   async QuerySpans(req) {
     // Accept a typed message or a plain init object (coerced to the typed type).
     const message =
-      req instanceof trace.QueryRequest
+      req instanceof span.QueryRequest
         ? req
-        : new trace.QueryRequest(req);
-    const request = trace.QueryRequest.toObject(message);
+        : new span.QueryRequest(req);
+    const request = span.QueryRequest.toObject(message);
     
     // Make gRPC call (tracing handled by base Client class)
-    return this.callUnary("QuerySpans", request, (res) => trace.QueryResponse.fromObject(res));
+    return this.callUnary("QuerySpans", request, (res) => span.QueryResponse.fromObject(res));
   }
 }

package/src/generated/services/{trace → span}/service.js

@@ -1,15 +1,15 @@
 /* eslint no-unused-vars: "off" */
 
-import { trace } from "@forwardimpact/libtype";
+import { span } from "@forwardimpact/libtype";
 
 /**
- * Base class for Trace service implementation
+ * Base class for Span service implementation
  */
-export class TraceBase {
+export class SpanBase {
   config;
 
   /**
-   * Creates a new Trace service instance
+   * Creates a new Span service instance
    * @param {object} config - Service configuration
    */
   constructor(config) {
@@ -19,8 +19,8 @@ export class TraceBase {
 
   /**
    * Must be implemented by subclass
-   * @param { trace.Span } req - Request parameters
-   * @returns { Promise<trace.RecordResponse> } Response object
+   * @param { span.SpanItem } req - Request parameters
+   * @returns { Promise<span.RecordResponse> } Response object
    */
   async RecordSpan(req) {
     throw new Error("RecordSpan not implemented");
@@ -28,8 +28,8 @@ export class TraceBase {
 
   /**
    * Must be implemented by subclass
-   * @param { trace.QueryRequest } req - Request parameters
-   * @returns { Promise<trace.QueryResponse> } Response object
+   * @param { span.QueryRequest } req - Request parameters
+   * @returns { Promise<span.QueryResponse> } Response object
    */
   async QuerySpans(req) {
     throw new Error("QuerySpans not implemented");
@@ -43,18 +43,18 @@ export class TraceBase {
     return {
       RecordSpan: async (call) => {
         // Validate and convert request
-        const error = trace.Span.verify(call.request);
+        const error = span.SpanItem.verify(call.request);
         if (error) throw new Error(`RecordSpan: ${error}`);
-        const req = trace.Span.fromObject(call.request);
+        const req = span.SpanItem.fromObject(call.request);
         
         // Call implementation
         return await this.RecordSpan(req);
       },
       QuerySpans: async (call) => {
         // Validate and convert request
-        const error = trace.QueryRequest.verify(call.request);
+        const error = span.QueryRequest.verify(call.request);
         if (error) throw new Error(`QuerySpans: ${error}`);
-        const req = trace.QueryRequest.fromObject(call.request);
+        const req = span.QueryRequest.fromObject(call.request);
         
         // Call implementation
         return await this.QuerySpans(req);