@x12i/helpers 1.0.1 → 1.1.0

package/src/helpers/api-contracts.js

@@ -0,0 +1,398 @@
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║                    API CONTRACTS                            ║
+ * ╠══════════════════════════════════════════════════════════════╣
+ * ║  Define API protocols, request/response shapes, validation, ║
+ * ║  serialization, and authentication schemes.                 ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * A "contract" fully describes one side of an API call:
+ *   - protocol  (rest | graphql | jsonrpc | soap | custom)
+ *   - endpoint  (URL template, method, content-type)
+ *   - auth      (bearer | apikey | basic | header | query | oauth2 | custom)
+ *   - request   schema (params, headers, body)
+ *   - response  schema (body, headers, status mapping)
+ *   - serializer / deserializer per protocol
+ */
+
+// ═══════════════════════════════════════════════════════════════
+//  VALIDATION  (lightweight JSON-schema-ish)
+// ═══════════════════════════════════════════════════════════════
+
+const TYPES = {
+  string: (v) => typeof v === "string",
+  number: (v) => typeof v === "number" && !Number.isNaN(v),
+  boolean: (v) => typeof v === "boolean",
+  object: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+  array: (v) => Array.isArray(v),
+  any: () => true,
+};
+
+function validateSchema(data, schema, path = "") {
+  const errors = [];
+  if (!schema || typeof schema !== "object") return errors;
+  if (!data || typeof data !== "object") return errors;
+
+  for (const [field, rules] of Object.entries(schema)) {
+    if (!rules || typeof rules !== "object") continue;
+    const fullPath = path ? `${path}.${field}` : field;
+    const value = data[field];
+
+    if (rules.required && (value === undefined || value === null)) {
+      errors.push({ path: fullPath, message: "required" });
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+
+    if (rules.type && TYPES[rules.type] && !TYPES[rules.type](value)) {
+      errors.push({
+        path: fullPath,
+        message: `expected ${rules.type}`,
+        got: typeof value,
+      });
+    }
+    if (rules.enum && !rules.enum.includes(value)) {
+      errors.push({
+        path: fullPath,
+        message: `must be one of [${rules.enum}]`,
+        got: value,
+      });
+    }
+    if (rules.pattern && typeof value === "string" && !new RegExp(rules.pattern).test(value)) {
+      errors.push({ path: fullPath, message: `must match ${rules.pattern}` });
+    }
+    if (rules.min !== undefined && value < rules.min) {
+      errors.push({ path: fullPath, message: `min ${rules.min}`, got: value });
+    }
+    if (rules.max !== undefined && value > rules.max) {
+      errors.push({ path: fullPath, message: `max ${rules.max}`, got: value });
+    }
+    if (rules.properties && typeof value === "object") {
+      errors.push(...validateSchema(value, rules.properties, fullPath));
+    }
+    if (rules.items && Array.isArray(value)) {
+      value.forEach((el, i) => {
+        if (rules.items.type && TYPES[rules.items.type] && !TYPES[rules.items.type](el)) {
+          errors.push({ path: `${fullPath}[${i}]`, message: `expected ${rules.items.type}` });
+        }
+        if (rules.items.properties && typeof el === "object") {
+          errors.push(...validateSchema(el, rules.items.properties, `${fullPath}[${i}]`));
+        }
+      });
+    }
+    if (rules.validate && !rules.validate(value, data)) {
+      errors.push({ path: fullPath, message: rules.validateMsg || "custom validation failed" });
+    }
+  }
+  return errors;
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  AUTH SCHEMES
+// ═══════════════════════════════════════════════════════════════
+
+const AUTH_HANDLERS = {
+  bearer: (creds, req) => {
+    req.headers = req.headers || {};
+    req.headers["Authorization"] = `Bearer ${creds.token}`;
+  },
+  basic: (creds, req) => {
+    req.headers = req.headers || {};
+    const encoded =
+      typeof btoa === "function"
+        ? btoa(`${creds.username}:${creds.password}`)
+        : Buffer.from(`${creds.username}:${creds.password}`).toString("base64");
+    req.headers["Authorization"] = `Basic ${encoded}`;
+  },
+  apikey: (creds, req) => {
+    if (creds.in === "query") {
+      req.query = req.query || {};
+      req.query[creds.name || "api_key"] = creds.key;
+    } else {
+      req.headers = req.headers || {};
+      req.headers[creds.name || "X-API-Key"] = creds.key;
+    }
+  },
+  header: (creds, req) => {
+    req.headers = req.headers || {};
+    req.headers[creds.name] = creds.value;
+  },
+  query: (creds, req) => {
+    req.query = req.query || {};
+    req.query[creds.name] = creds.value;
+  },
+  oauth2: (creds, req) => {
+    req.headers = req.headers || {};
+    req.headers["Authorization"] = `Bearer ${creds.accessToken}`;
+  },
+  custom: (creds, req) => {
+    if (creds.apply) creds.apply(req);
+  },
+};
+
+function applyAuth(authConfig, credentials, request) {
+  if (!authConfig || !credentials) return;
+  const handler = AUTH_HANDLERS[authConfig.type];
+  if (handler) handler(credentials, request);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  PROTOCOL SERIALIZERS
+// ═══════════════════════════════════════════════════════════════
+
+function escapeXml(val) {
+  if (val == null) return "";
+  return String(val)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+const PROTOCOLS = {
+  // ── REST ───────────────────────────────────
+  rest: {
+    name: "REST",
+    buildRequest(contract, params) {
+      let url = contract.endpoint || "";
+      const { pathParams = {}, queryParams = {}, body = null, headers = {} } = params;
+
+      url = url.replace(/[:{}](\w+)}?/g, (_, key) => {
+        const val = pathParams[key];
+        if (val === undefined) throw new Error(`Missing path param: ${key}`);
+        return encodeURIComponent(val);
+      });
+
+      return {
+        url,
+        method: (contract.method || "GET").toUpperCase(),
+        headers: {
+          "Content-Type": contract.contentType || "application/json",
+          ...contract.defaultHeaders,
+          ...headers,
+        },
+        query: { ...contract.defaultQuery, ...queryParams },
+        body: body != null ? body : undefined,
+      };
+    },
+    parseResponse(_c, raw) {
+      return {
+        status: raw.status,
+        headers: raw.headers || {},
+        data: raw.body,
+        error: raw.status >= 400 ? raw.body?.error || raw.body?.message || raw.statusText : null,
+      };
+    },
+  },
+
+  // ── GRAPHQL ────────────────────────────────
+  graphql: {
+    name: "GraphQL",
+    buildRequest(contract, params) {
+      const { variables = {}, headers = {}, operationName } = params;
+      const query = params.query || contract.query || contract.mutation;
+      if (!query) throw new Error("GraphQL contract requires query or mutation");
+
+      return {
+        url: contract.endpoint,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...contract.defaultHeaders, ...headers },
+        query: {},
+        body: { query, variables, ...(operationName ? { operationName } : {}) },
+      };
+    },
+    parseResponse(_c, raw) {
+      const body = raw.body || {};
+      return {
+        status: raw.status,
+        headers: raw.headers || {},
+        data: body.data || null,
+        error: body.errors ? body.errors.map((e) => e.message).join("; ") : null,
+      };
+    },
+  },
+
+  // ── JSON-RPC 2.0 ──────────────────────────
+  jsonrpc: {
+    name: "JSON-RPC 2.0",
+    buildRequest(contract, params) {
+      const { rpcParams = {}, headers = {}, id = 1 } = params;
+      return {
+        url: contract.endpoint,
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...contract.defaultHeaders, ...headers },
+        query: {},
+        body: {
+          jsonrpc: "2.0",
+          id,
+          method: contract.rpcMethod,
+          params: contract.paramsAsArray ? Object.values(rpcParams) : rpcParams,
+        },
+      };
+    },
+    parseResponse(_c, raw) {
+      const body = raw.body || {};
+      return {
+        status: raw.status,
+        headers: raw.headers || {},
+        data: body.result ?? null,
+        error: body.error ? `${body.error.code}: ${body.error.message}` : null,
+      };
+    },
+  },
+
+  // ── SOAP ───────────────────────────────────
+  soap: {
+    name: "SOAP",
+    buildRequest(contract, params) {
+      const { soapBody = {}, headers = {}, soapHeaders = {} } = params;
+      const ns = contract.namespace || "http://tempuri.org/";
+      const action = contract.soapAction || contract.operation;
+
+      const bodyXml = Object.entries(soapBody)
+        .map(([k, v]) => `      <ns:${k}>${escapeXml(v)}</ns:${k}>`)
+        .join("\n");
+      const headerXml = Object.entries(soapHeaders)
+        .map(([k, v]) => `      <ns:${k}>${escapeXml(v)}</ns:${k}>`)
+        .join("\n");
+
+      const envelope = `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="${ns}">
+  <soap:Header>\n${headerXml}\n  </soap:Header>
+  <soap:Body>
+    <ns:${contract.operation}>\n${bodyXml}\n    </ns:${contract.operation}>
+  </soap:Body>
+</soap:Envelope>`;
+
+      return {
+        url: contract.endpoint,
+        method: "POST",
+        headers: {
+          "Content-Type": "text/xml; charset=utf-8",
+          SOAPAction: action,
+          ...contract.defaultHeaders,
+          ...headers,
+        },
+        query: {},
+        body: envelope,
+      };
+    },
+    parseResponse(contract, raw) {
+      const data = contract.responseExtractor ? contract.responseExtractor(raw.body) : raw.body;
+      return {
+        status: raw.status,
+        headers: raw.headers || {},
+        data,
+        error: raw.status >= 400 ? raw.body : null,
+      };
+    },
+  },
+
+  // ── CUSTOM ─────────────────────────────────
+  custom: {
+    name: "Custom",
+    buildRequest(contract, params) {
+      if (!contract.buildRequest) throw new Error("Custom protocol needs buildRequest()");
+      return contract.buildRequest(params);
+    },
+    parseResponse(contract, raw) {
+      if (!contract.parseResponse) return { status: raw.status, data: raw.body, error: null };
+      return contract.parseResponse(raw);
+    },
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════
+//  CONTRACT BUILDER
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * @param {object} config
+ * @param {string} config.name               – "getUser", "createOrder"
+ * @param {string} config.protocol            – "rest"|"graphql"|"jsonrpc"|"soap"|"custom"
+ * @param {string} config.endpoint            – URL or URL template
+ * @param {string} [config.method]            – HTTP method (REST)
+ * @param {string} [config.query]             – GQL query
+ * @param {string} [config.mutation]          – GQL mutation
+ * @param {string} [config.rpcMethod]         – JSON-RPC method name
+ * @param {string} [config.operation]         – SOAP operation
+ * @param {string} [config.namespace]         – SOAP namespace
+ * @param {string} [config.soapAction]        – SOAP action header
+ * @param {object} [config.auth]              – { type, ... }
+ * @param {object} [config.requestSchema]     – validation for params
+ * @param {object} [config.responseSchema]    – validation for response data
+ * @param {object} [config.defaultHeaders]
+ * @param {object} [config.defaultQuery]
+ * @param {string} [config.contentType]
+ * @param {function} [config.buildRequest]      – custom protocol
+ * @param {function} [config.parseResponse]     – custom protocol
+ * @param {function} [config.responseExtractor] – SOAP
+ * @param {boolean}  [config.paramsAsArray]     – JSON-RPC
+ */
+function defineContract(config) {
+  const protocol = PROTOCOLS[config.protocol];
+  if (!protocol) {
+    throw new Error(`Unknown protocol "${config.protocol}". Use: ${Object.keys(PROTOCOLS).join(", ")}`);
+  }
+
+  return {
+    ...config,
+    _protocol: protocol,
+
+    validateRequest(params) {
+      if (!config.requestSchema) return { valid: true, errors: [] };
+      const errors = validateSchema(params, config.requestSchema);
+      return { valid: errors.length === 0, errors };
+    },
+
+    validateResponse(data) {
+      if (!config.responseSchema) return { valid: true, errors: [] };
+      const safe = data && typeof data === "object" ? data : {};
+      const errors = validateSchema(safe, config.responseSchema);
+      return { valid: errors.length === 0, errors };
+    },
+
+    buildRequest(params, credentials) {
+      const req = protocol.buildRequest(config, params);
+      if (config.auth && credentials) applyAuth(config.auth, credentials, req);
+      return req;
+    },
+
+    parseResponse(raw) {
+      return protocol.parseResponse(config, raw);
+    },
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  CONTRACT REGISTRY
+// ═══════════════════════════════════════════════════════════════
+
+function createRegistry() {
+  const contracts = new Map();
+  return {
+    register(config) {
+      const c = config._protocol ? config : defineContract(config);
+      contracts.set(c.name, c);
+      return c;
+    },
+    get(name) {
+      const c = contracts.get(name);
+      if (!c) throw new Error(`Contract "${name}" not registered`);
+      return c;
+    },
+    has: (name) => contracts.has(name),
+    list: () => [...contracts.keys()],
+    remove: (name) => contracts.delete(name),
+  };
+}
+
+module.exports = {
+  defineContract,
+  createRegistry,
+  validateSchema,
+  applyAuth,
+  PROTOCOLS,
+  AUTH_HANDLERS,
+};
+