@usu-accessibility/anumber-service-handler 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# `@usu-accessibility/anumber-service-handler`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed, server-side client for the A-Number Service. It authenticates with an
+API key and exposes the service's oRPC procedures with inferred TypeScript
+input and output types.
+
+## Install
+
+```sh
+npm install @usu-accessibility/anumber-service-handler
+```
+
+This package is ESM-only and requires a runtime with `fetch` support.
+
+## Configure
+
+Pass the service URL and authentication token when creating the client:
+
+```ts
+import { createAnumberHandler } from "@usu-accessibility/anumber-service-handler";
+
+const client = createAnumberHandler({
+  baseUrl: "https://anumber.example.edu",
+  authToken: process.env.ANUMBER_SERVICE_AUTH_TOKEN,
+});
+```
+
+The base URL should be the service origin, without `/rpc`. A trailing slash is
+accepted.
+
+Alternatively, configure both values through environment variables:
+
+```dotenv
+ANUMBER_SERVICE_URL=https://anumber.example.edu
+ANUMBER_SERVICE_AUTH_TOKEN=...
+```
+
+```ts
+import { createAnumberHandler } from "@usu-accessibility/anumber-service-handler";
+
+const client = createAnumberHandler();
+```
+
+Explicit options take precedence over environment variables. The constructor
+throws when either value is missing. Keep the authentication token on the
+server; do not bundle it into browser code.
+
+## Encrypt A-Numbers
+
+Use `client.anumber.encrypt` to convert A-Numbers into safe IDs:
+
+```ts
+const result = await client.anumber.encrypt({
+  aNumbers: ["a12345678", "a87654321"],
+});
+
+console.log(result.data.a12345678); // "anum_..."
+console.log(result.errors); // A-Numbers that could not be processed
+```
+
+A-Numbers must start with `a` followed by digits. Input is normalized to
+lowercase. Encrypting the same A-Number repeatedly returns its existing safe
+ID.
+
+## Decrypt safe IDs
+
+Use `client.anumber.decrypt` to resolve safe IDs:
+
+```ts
+const result = await client.anumber.decrypt({
+  ids: ["anum_..."],
+});
+
+console.log(result.data["anum_..."]); // "a12345678"
+console.log(result.errors); // IDs that were not found or could not be processed
+```
+
+Safe IDs must start with `anum_`. Both operations return:
+
+- `data` — a record mapping each input value to its resolved output.
+- `errors` — inputs that could not be resolved.
+
+Authentication and input-validation failures reject the call rather than being
+included in `errors`.
+
+## Build from this repository
+
+From the repository root:
+
+```sh
+npm install
+npm run build:handler
+```
+
+The ESM bundle, source map, and TypeScript declarations are written to `dist`.

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import * as _orpc_server from '@orpc/server';
+import { RouterClient } from '@orpc/server';
+import * as zod_v4_core from 'zod/v4/core';
+import * as zod from 'zod';
+import * as _usu_accessibility_auth_service_handler from '@usu-accessibility/auth-service-handler';
+
+declare const router: {
+    anumber: {
+        encrypt: _orpc_server.DecoratedProcedure<{
+            headers: Headers;
+        } & object, {
+            user: {
+                type: "user";
+                user: _usu_accessibility_auth_service_handler.Session["user"];
+            } | {
+                type: "api_key";
+                user: {
+                    aNumber?: string;
+                };
+            };
+        }, zod.ZodObject<{
+            aNumbers: zod.ZodArray<zod.ZodString>;
+        }, zod_v4_core.$strip>, zod.ZodObject<{
+            data: zod.ZodRecord<zod.ZodString, zod.ZodString>;
+            errors: zod.ZodArray<zod.ZodString>;
+        }, zod_v4_core.$strip>, Record<never, never>>;
+        decrypt: _orpc_server.DecoratedProcedure<{
+            headers: Headers;
+        } & object, {
+            user: {
+                type: "user";
+                user: _usu_accessibility_auth_service_handler.Session["user"];
+            } | {
+                type: "api_key";
+                user: {
+                    aNumber?: string;
+                };
+            };
+        }, zod.ZodObject<{
+            ids: zod.ZodArray<zod.ZodString>;
+        }, zod_v4_core.$strip>, zod.ZodObject<{
+            data: zod.ZodRecord<zod.ZodString, zod.ZodString>;
+            errors: zod.ZodArray<zod.ZodString>;
+        }, zod_v4_core.$strip>, Record<never, never>>;
+    };
+};
+type AppRouter = typeof router;
+type Client = RouterClient<AppRouter>;
+
+type CreateAnumberHandlerOptions = {
+    baseUrl?: string;
+    authToken?: string;
+};
+declare function createAnumberHandler(options?: CreateAnumberHandlerOptions): Client;
+
+export { type Client, type CreateAnumberHandlerOptions, createAnumberHandler };

package/dist/index.js

@@ -0,0 +1,33 @@
+// src/index.ts
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+function resolveOptions(options) {
+  const baseUrl = options?.baseUrl ?? process.env.ANUMBER_SERVICE_URL;
+  const authToken = options?.authToken ?? process.env.ANUMBER_SERVICE_AUTH_TOKEN;
+  if (!baseUrl) {
+    throw new Error(
+      "Missing baseUrl: pass options.baseUrl or set ANUMBER_SERVICE_URL"
+    );
+  }
+  if (!authToken) {
+    throw new Error(
+      "Missing authToken: pass options.authToken or set ANUMBER_SERVICE_AUTH_TOKEN"
+    );
+  }
+  return { baseUrl, authToken };
+}
+function createAnumberHandler(options) {
+  const resolved = resolveOptions(options);
+  const link = new RPCLink({
+    origin: resolved.baseUrl.replace(/\/$/, ""),
+    url: "/rpc",
+    headers: {
+      Authorization: `Bearer ${resolved.authToken}`
+    }
+  });
+  return createORPCClient(link);
+}
+export {
+  createAnumberHandler
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createORPCClient } from \"@orpc/client\";\nimport { RPCLink } from \"@orpc/client/fetch\";\nimport type { Client } from \"@anumber-service/web/rpc\";\n\nexport type { Client };\n\nexport type CreateAnumberHandlerOptions = {\n  baseUrl?: string;\n  authToken?: string;\n};\n\nfunction resolveOptions(options?: CreateAnumberHandlerOptions) {\n  const baseUrl = options?.baseUrl ?? process.env.ANUMBER_SERVICE_URL;\n  const authToken =\n    options?.authToken ?? process.env.ANUMBER_SERVICE_AUTH_TOKEN;\n\n  if (!baseUrl) {\n    throw new Error(\n      \"Missing baseUrl: pass options.baseUrl or set ANUMBER_SERVICE_URL\",\n    );\n  }\n\n  if (!authToken) {\n    throw new Error(\n      \"Missing authToken: pass options.authToken or set ANUMBER_SERVICE_AUTH_TOKEN\",\n    );\n  }\n\n  return { baseUrl, authToken };\n}\n\nexport function createAnumberHandler(\n  options?: CreateAnumberHandlerOptions,\n): Client {\n  const resolved = resolveOptions(options);\n\n  const link = new RPCLink({\n    origin: resolved.baseUrl.replace(/\\/$/, \"\"),\n    url: \"/rpc\",\n    headers: {\n      Authorization: `Bearer ${resolved.authToken}`,\n    },\n  });\n\n  return createORPCClient(link) as Client;\n}\n"],"mappings":";AAAA,SAAS,wBAAwB;AACjC,SAAS,eAAe;AAUxB,SAAS,eAAe,SAAuC;AAC7D,QAAM,UAAU,SAAS,WAAW,QAAQ,IAAI;AAChD,QAAM,YACJ,SAAS,aAAa,QAAQ,IAAI;AAEpC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,WAAW;AACd,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,UAAU;AAC9B;AAEO,SAAS,qBACd,SACQ;AACR,QAAM,WAAW,eAAe,OAAO;AAEvC,QAAM,OAAO,IAAI,QAAQ;AAAA,IACvB,QAAQ,SAAS,QAAQ,QAAQ,OAAO,EAAE;AAAA,IAC1C,KAAK;AAAA,IACL,SAAS;AAAA,MACP,eAAe,UAAU,SAAS,SAAS;AAAA,IAC7C;AAAA,EACF,CAAC;AAED,SAAO,iBAAiB,IAAI;AAC9B;","names":[]}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@usu-accessibility/anumber-service-handler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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": "tsup"
+  },
+  "dependencies": {
+    "@orpc/client": "2.0.0-beta.44",
+    "@orpc/server": "2.0.0-beta.44",
+    "@usu-accessibility/auth-service-handler": "^1.0.25",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@anumber-service/web": "*",
+    "@types/node": "^20",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  }
+}