@x12i/helpers 1.0.1 → 1.1.0

package/README.md

@@ -72,6 +72,80 @@ Direct import:
 const { requestToCurl } = require("@x12i/helpers/http-tools");
 ```
 
+### API contracts + protocol bridge
+
+Define protocol-aware API contracts (REST/GraphQL/JSON-RPC/SOAP/custom) with optional request/response validation and auth application.
+
+```js
+const { defineContract, createRegistry } = require("@x12i/helpers/api-contracts");
+const { createBridge } = require("@x12i/helpers/api-mapper");
+
+const registry = createRegistry();
+
+registry.register({
+  name: "restGetUser",
+  protocol: "rest",
+  endpoint: "/api/users/{id}",
+  method: "GET",
+  auth: { type: "bearer" },
+});
+
+registry.register({
+  name: "gqlGetUser",
+  protocol: "graphql",
+  endpoint: "https://api.example.com/graphql",
+  query: "query GetUser($userId: ID!) { user(id: $userId) { id fullName } }",
+  auth: { type: "bearer" },
+});
+
+const bridge = createBridge({
+  source: "restGetUser",
+  target: "gqlGetUser",
+  registry,
+  requestMapping: [{ from: "pathParams.id", to: "variables.userId" }],
+  responseMapping: ["user.id", "user.fullName -> user.name"],
+  credentials: { target: { token: "TOKEN" } },
+});
+
+// bridge.call({ pathParams: { id: "42" } })
+```
+
+Direct imports:
+
+```js
+const { createBridge, batchCall, chainBridges } = require("@x12i/helpers/api-mapper");
+const { defineContract, createRegistry } = require("@x12i/helpers/api-contracts");
+```
+
+### Firebase Realtime Database (native) — mongo-like helper
+
+This helper uses the Firebase Admin SDK and wraps RTDB with a familiar Mongo-ish API (`findOne`, `insertOne`, `updateOne`, etc.).
+
+1) Create `.env` (see `.env.example`) and put credentials in `.secrets/firebase-service-account.json`.
+
+2) Use it:
+
+```js
+const { initFirebaseRtdb } = require("@x12i/helpers/firebase-rtdb");
+
+const fb = initFirebaseRtdb(); // loads .env by default
+const users = fb.collection("users");
+
+const { insertedId } = await users.insertOne({ email: "a@b.com", name: "Ami" });
+const user = await users.findOne({ _id: insertedId });
+
+await users.updateOne({ _id: insertedId }, { $set: { name: "Ami N." }, $inc: { loginCount: 1 } });
+await users.deleteOne({ _id: insertedId });
+```
+
+If you want native RTDB query features (server-side indexed filtering), use `query()`:
+
+```js
+const result = await users
+  .query({ orderByChild: "email", equalTo: "a@b.com", limitToFirst: 10 })
+  .find();
+```
+
 ## API
 
 - `mapObject(source, mapping, opts)`
@@ -83,4 +157,11 @@ const { requestToCurl } = require("@x12i/helpers/http-tools");
 - `curlToRequest(curlCommand)`
 - `buildUrl(baseUrl, pathOrUrl, query)`
 - `createBaseUrlClient(baseUrl, defaults)`
+- `defineContract(config)`
+- `createRegistry()`
+- `createBridge(config)`
+- `batchCall(bridge, paramsList, opts)`
+- `chainBridges(...bridges)`
+- `initFirebaseRtdb(options)`
+- `getFirebaseRtdb()`
 

package/dist/access-definition/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './integration/integrationDefinition.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/access-definition/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/access-definition/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,wCAAwC,CAAC"}

package/dist/access-definition/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./integration/integrationDefinition.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/access-definition/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/access-definition/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,yEAAuD"}

package/dist/access-definition/integration/integrationDefinition.d.ts

@@ -0,0 +1,2 @@
+export type { IntegrationDefinition, SubjectBinding } from '../types.js';
+//# sourceMappingURL=integrationDefinition.d.ts.map

package/dist/access-definition/integration/integrationDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationDefinition.d.ts","sourceRoot":"","sources":["../../../src/access-definition/integration/integrationDefinition.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/access-definition/integration/integrationDefinition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=integrationDefinition.js.map

package/dist/access-definition/integration/integrationDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrationDefinition.js","sourceRoot":"","sources":["../../../src/access-definition/integration/integrationDefinition.ts"],"names":[],"mappings":""}

package/dist/access-definition/types.d.ts

@@ -0,0 +1,43 @@
+export type AccessLevel = 'public' | 'static-secret' | 'runtime-token' | 'delegated-consent' | 'signed-request' | 'transport-bound' | 'composite';
+export type StorageMode = 'mode-1' | 'mode-2' | 'mode-3';
+export type CredentialKind = 'none' | 'api-key' | 'basic-auth' | 'bearer-token' | 'oauth-access-token' | 'refresh-token' | 'consent-token' | 'session-token' | 'custom-header-secret' | 'hmac-key' | 'jwt-assertion-key' | 'client-certificate';
+export type AcquisitionType = 'preset' | 'client-credentials' | 'authorization-code' | 'refresh-token' | 'token-exchange' | 'login-session' | 'device-code' | 'signed-jwt' | 'manual';
+export type InjectionType = 'header' | 'query' | 'basic-authorization' | 'bearer-authorization' | 'form-body' | 'transport' | 'signature';
+export type PersistenceClass = 'none' | 'ephemeral-memory' | 'local-encrypted' | 'firebase-atm' | 'external-atm';
+export type SecretMaterialClass = 'preset-secret' | 'bootstrap-secret' | 'runtime-token' | 'refresh-material' | 'consent-material' | 'signing-material' | 'transport-identity';
+export type SubjectBinding = 'none' | 'tenant' | 'user' | 'custom';
+export type AccessLeafDefinition = {
+    accessLevel: Exclude<AccessLevel, 'composite'>;
+    credentialKinds?: CredentialKind[];
+    acquisitionType?: AcquisitionType;
+    injectionTypes?: InjectionType[];
+    persistenceClass?: PersistenceClass;
+    refreshSupported?: boolean;
+    consentRequired?: boolean;
+    signingRequired?: boolean;
+    transportRequired?: boolean;
+    /**
+     * References to preset/bootstrap secrets needed to operate this integration.
+     * Examples: `secret.hubspot.clientSecret`, `secret.aws.signingKey`.
+     */
+    secretRefs?: string[];
+    /**
+     * References to runtime material produced/consumed by this integration.
+     * Examples: `material.hubspot.refresh-token.default`.
+     */
+    tokenRefs?: string[];
+};
+export type AccessCompositeDefinition = {
+    accessLevel: 'composite';
+    layers: AccessDefinition[];
+};
+export type AccessDefinition = AccessLeafDefinition | AccessCompositeDefinition;
+export type IntegrationDefinition = {
+    integrationId: string;
+    access: AccessDefinition;
+    defaults?: {
+        subjectBinding?: SubjectBinding;
+        storageMode?: StorageMode;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/access-definition/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/access-definition/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,CAAC;AAEhB,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,YAAY,GACZ,cAAc,GACd,oBAAoB,GACpB,eAAe,GACf,eAAe,GACf,eAAe,GACf,sBAAsB,GACtB,UAAU,GACV,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,oBAAoB,GACpB,oBAAoB,GACpB,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,OAAO,GACP,qBAAqB,GACrB,sBAAsB,GACtB,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,kBAAkB,GAClB,iBAAiB,GACjB,cAAc,GACd,cAAc,CAAC;AAEnB,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,kBAAkB,GAClB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnE,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAC/C,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,yBAAyB,CAAC;AAEhF,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,CAAC,EAAE;QACT,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,WAAW,CAAC,EAAE,WAAW,CAAC;KAC3B,CAAC;CACH,CAAC"}

package/dist/access-definition/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/access-definition/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/access-definition/types.ts"],"names":[],"mappings":""}

package/index.js

@@ -1,5 +1,8 @@
 module.exports = {
   ...require("./src/helpers/objectsMapper.js"),
   ...require("./src/helpers/httpTools.js"),
+  ...require("./src/helpers/apiMapper.js"),
+  ...require("./src/helpers/api-contracts.js"),
+  ...require("./src/helpers/firebaseRtdb.js"),
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/helpers",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Small helper utilities for x12i projects.",
   "license": "MIT",
   "author": "x12i",
@@ -21,15 +21,36 @@
   "exports": {
     ".": "./index.js",
     "./objects-mapper": "./src/helpers/objectsMapper.js",
-    "./http-tools": "./src/helpers/httpTools.js"
+    "./http-tools": "./src/helpers/httpTools.js",
+    "./api-mapper": "./src/helpers/apiMapper.js",
+    "./api-contracts": "./src/helpers/api-contracts.js",
+    "./firebase-rtdb": "./src/helpers/firebaseRtdb.js",
+    "./access-definition": {
+      "types": "./dist/access-definition/index.d.ts",
+      "require": "./dist/access-definition/index.js"
+    },
+    "./access-definition/*": {
+      "types": "./dist/access-definition/*.d.ts",
+      "require": "./dist/access-definition/*.js"
+    }
   },
   "files": [
     "index.js",
+    "dist/",
     "src/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "build": "npx tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
     "test": "node --test"
+  },
+  "dependencies": {
+    "firebase-admin": "^13.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
   }
 }

package/src/access-definition/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './integration/integrationDefinition.js';
+

package/src/access-definition/integration/integrationDefinition.ts

@@ -0,0 +1,2 @@
+export type { IntegrationDefinition, SubjectBinding } from '../types.js';
+

package/src/access-definition/types.ts

@@ -0,0 +1,104 @@
+export type AccessLevel =
+  | 'public'
+  | 'static-secret'
+  | 'runtime-token'
+  | 'delegated-consent'
+  | 'signed-request'
+  | 'transport-bound'
+  | 'composite';
+
+export type StorageMode = 'mode-1' | 'mode-2' | 'mode-3';
+
+export type CredentialKind =
+  | 'none'
+  | 'api-key'
+  | 'basic-auth'
+  | 'bearer-token'
+  | 'oauth-access-token'
+  | 'refresh-token'
+  | 'consent-token'
+  | 'session-token'
+  | 'custom-header-secret'
+  | 'hmac-key'
+  | 'jwt-assertion-key'
+  | 'client-certificate';
+
+export type AcquisitionType =
+  | 'preset'
+  | 'client-credentials'
+  | 'authorization-code'
+  | 'refresh-token'
+  | 'token-exchange'
+  | 'login-session'
+  | 'device-code'
+  | 'signed-jwt'
+  | 'manual';
+
+export type InjectionType =
+  | 'header'
+  | 'query'
+  | 'basic-authorization'
+  | 'bearer-authorization'
+  | 'form-body'
+  | 'transport'
+  | 'signature';
+
+export type PersistenceClass =
+  | 'none'
+  | 'ephemeral-memory'
+  | 'local-encrypted'
+  | 'firebase-atm'
+  | 'external-atm';
+
+export type SecretMaterialClass =
+  | 'preset-secret'
+  | 'bootstrap-secret'
+  | 'runtime-token'
+  | 'refresh-material'
+  | 'consent-material'
+  | 'signing-material'
+  | 'transport-identity';
+
+export type SubjectBinding = 'none' | 'tenant' | 'user' | 'custom';
+
+export type AccessLeafDefinition = {
+  accessLevel: Exclude<AccessLevel, 'composite'>;
+  credentialKinds?: CredentialKind[];
+  acquisitionType?: AcquisitionType;
+  injectionTypes?: InjectionType[];
+  persistenceClass?: PersistenceClass;
+
+  refreshSupported?: boolean;
+  consentRequired?: boolean;
+  signingRequired?: boolean;
+  transportRequired?: boolean;
+
+  /**
+   * References to preset/bootstrap secrets needed to operate this integration.
+   * Examples: `secret.hubspot.clientSecret`, `secret.aws.signingKey`.
+   */
+  secretRefs?: string[];
+
+  /**
+   * References to runtime material produced/consumed by this integration.
+   * Examples: `material.hubspot.refresh-token.default`.
+   */
+  tokenRefs?: string[];
+};
+
+export type AccessCompositeDefinition = {
+  accessLevel: 'composite';
+  layers: AccessDefinition[];
+};
+
+export type AccessDefinition = AccessLeafDefinition | AccessCompositeDefinition;
+
+export type IntegrationDefinition = {
+  integrationId: string;
+  access: AccessDefinition;
+  defaults?: {
+    subjectBinding?: SubjectBinding;
+    storageMode?: StorageMode;
+  };
+};
+