@oatfi/oatfi-sdk-ts 0.11.65 → 0.11.67

package/scripts/fix-overlay.ts

@@ -0,0 +1,449 @@
+#!/usr/bin/env -S npx tsx
+
+/**
+ * fix-overlay.ts
+ *
+ * Analyzes the OpenAPI spec and generates missing method-name overlay entries
+ * for the Speakeasy SDK, mimicking the Web Studio's naming optimization.
+ *
+ * Usage:
+ *   npx tsx scripts/fix-overlay.ts          # dry-run (shows what would change)
+ *   npx tsx scripts/fix-overlay.ts --apply  # writes changes to overlay file
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const ROOT = resolve(import.meta.dirname, "..");
+const SPEC_PATH = resolve(ROOT, ".speakeasy/out.openapi.yaml");
+const OVERLAY_PATH = resolve(ROOT, ".speakeasy/speakeasy-modifications-overlay.yaml");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+interface SpecOperation {
+  path: string;
+  method: string;
+  operationId: string;
+}
+
+interface NamingResult {
+  group: string | null;
+  methodName: string;
+  confidence: "high" | "low";
+}
+
+interface OverlayEntry {
+  operation: SpecOperation;
+  naming: NamingResult;
+  yamlBlock: string;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Parse the OpenAPI spec for all operations
+// ---------------------------------------------------------------------------
+function extractSpecOperations(specPath: string): SpecOperation[] {
+  console.log(`Reading spec from ${specPath}...`);
+  const content = readFileSync(specPath, "utf8");
+  const spec = parseYaml(content);
+
+  const operations: SpecOperation[] = [];
+  const httpMethods = new Set([
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+  ]);
+
+  if (!spec.paths) {
+    throw new Error("No paths found in spec");
+  }
+
+  for (const [path, pathObj] of Object.entries<any>(spec.paths)) {
+    for (const [method, opObj] of Object.entries<any>(pathObj)) {
+      if (httpMethods.has(method) && opObj?.operationId) {
+        operations.push({
+          path,
+          method,
+          operationId: opObj.operationId,
+        });
+      }
+    }
+  }
+
+  console.log(`  Found ${operations.length} operations in spec.`);
+  return operations;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Parse existing overlay to find covered operationIds
+// ---------------------------------------------------------------------------
+function extractCoveredOperationIds(overlayPath: string): Set<string> {
+  const content = readFileSync(overlayPath, "utf8");
+  const covered = new Set<string>();
+
+  // Extract operationId from "before:" metadata lines
+  // Format: before: sdk.Group.ControllerName_action()
+  const beforeRegex = /before:\s+sdk\.[^.]+\.(\w+Controller_\w+)\(\)/g;
+  let match: RegExpExecArray | null;
+  while ((match = beforeRegex.exec(content)) !== null) {
+    covered.add(match[1]);
+  }
+
+  console.log(`  Found ${covered.size} covered operations in overlay.`);
+  return covered;
+}
+
+// ---------------------------------------------------------------------------
+// 3. Parse current overlay version
+// ---------------------------------------------------------------------------
+function getOverlayVersion(overlayPath: string): string {
+  const content = readFileSync(overlayPath, "utf8");
+  const match = content.match(/version:\s+([\d.]+)/);
+  return match?.[1] ?? "0.0.0";
+}
+
+function bumpPatchVersion(version: string): string {
+  const parts = version.split(".");
+  parts[parts.length - 1] = String(Number(parts[parts.length - 1]) + 1);
+  return parts.join(".");
+}
+
+// ---------------------------------------------------------------------------
+// 4. Naming rules
+// ---------------------------------------------------------------------------
+
+/** Split PascalCase into words: "BusinessFiles" -> ["Business", "Files"] */
+function splitPascalCase(str: string): string[] {
+  return str.match(/[A-Z][a-z0-9]*/g) ?? [str];
+}
+
+/** PascalCase to camelCase: "BusinessFiles" -> "businessFiles" */
+function toCamelCase(str: string): string {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
+/** Check if name has multiple PascalCase words */
+function isMultiWord(name: string): boolean {
+  return splitPascalCase(name).length > 1;
+}
+
+/** PascalCase to display form: "BusinessFiles" -> "Business Files" */
+function toDisplayGroup(name: string): string {
+  return splitPascalCase(name).join(" ");
+}
+
+/** Simple English singularization */
+function singularize(word: string): string {
+  if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (word.endsWith("ses") && !word.endsWith("sses"))
+    return word.slice(0, -2);
+  if (word.endsWith("s") && !word.endsWith("ss") && !word.endsWith("us"))
+    return word.slice(0, -1);
+  return word;
+}
+
+/**
+ * Derive a clean SDK method name from an operationId.
+ *
+ * Handles:
+ * - Standard CRUD: create, findAll, findOne, update, remove, delete, search
+ * - File operations: uploadFiles, downloadFile
+ * - CRUD with resource suffix: listBillingCycles -> list
+ * - Actions with resource suffix: submitApplication -> submit
+ * - Compound resource stripping: getAllBusinessBalances -> listBalances
+ * - Fallback: keeps action as-is with low confidence
+ */
+function deriveNames(operationId: string): NamingResult {
+  const underscoreIdx = operationId.indexOf("_");
+  if (underscoreIdx === -1) {
+    return {
+      group: null,
+      methodName: toCamelCase(operationId),
+      confidence: "low",
+    };
+  }
+
+  const controllerPart = operationId.slice(0, underscoreIdx);
+  const action = operationId.slice(underscoreIdx + 1);
+  const resourceName = controllerPart.replace(/Controller$/, "");
+
+  // Group: multi-word controllers need explicit override
+  const group = isMultiWord(resourceName) ? toCamelCase(resourceName) : null;
+
+  // --- Exact CRUD mappings (highest confidence) ---
+  const exactMap: Record<string, string> = {
+    create: "create",
+    findAll: "list",
+    findOne: "get",
+    findById: "get",
+    update: "update",
+    remove: "delete",
+    delete: "delete",
+    search: "search",
+    uploadFiles: "upload",
+    downloadFile: "download",
+  };
+
+  if (exactMap[action]) {
+    return { group, methodName: exactMap[action], confidence: "high" };
+  }
+
+  // --- CRUD + resource name stripping ---
+  const singularRes = singularize(resourceName);
+  const pluralRes = resourceName;
+
+  // Ordered by specificity: "getAll" before "get", "findBy" before "find"
+  const crudPrefixes: { prefix: string; verb: string }[] = [
+    { prefix: "getAll", verb: "list" },
+    { prefix: "findAll", verb: "list" },
+    { prefix: "findBy", verb: "listBy" },
+    { prefix: "list", verb: "list" },
+    { prefix: "get", verb: "get" },
+    { prefix: "create", verb: "create" },
+    { prefix: "update", verb: "update" },
+    { prefix: "delete", verb: "delete" },
+    { prefix: "remove", verb: "remove" },
+  ];
+
+  for (const { prefix, verb } of crudPrefixes) {
+    if (!action.startsWith(prefix) || action.length <= prefix.length) continue;
+    const suffix = action.slice(prefix.length);
+
+    // Full resource match: listBillingCycles -> list
+    if (suffix === singularRes || suffix === pluralRes) {
+      return { group, methodName: verb, confidence: "high" };
+    }
+
+    // Partial resource prefix match: getAllBusinessBalances -> listBalances
+    // (when controller is BusinessesController, singularRes = "Businesse" or "Business")
+    if (suffix.startsWith(singularRes) && suffix.length > singularRes.length) {
+      const remainder = suffix.slice(singularRes.length);
+      return {
+        group,
+        methodName: verb + remainder,
+        confidence: "high",
+      };
+    }
+
+    // Check using individual PascalCase words from resource name
+    const resourceWords = splitPascalCase(resourceName);
+    const suffixWords = splitPascalCase(suffix);
+
+    // Strip leading words that match resource words
+    let stripped = [...suffixWords];
+    for (const rw of resourceWords) {
+      if (
+        stripped.length > 0 &&
+        (stripped[0] === rw || stripped[0] === singularize(rw))
+      ) {
+        stripped.shift();
+      }
+    }
+
+    if (stripped.length > 0 && stripped.length < suffixWords.length) {
+      return {
+        group,
+        methodName: verb + stripped.join(""),
+        confidence: "high",
+      };
+    }
+
+    // Suffix resource match (e.g., regenerateApiKey on PlatformApiKeysController)
+    if (singularRes.endsWith(suffix) || singularRes.endsWith(singularize(suffix))) {
+      return { group, methodName: verb, confidence: "high" };
+    }
+  }
+
+  // --- Action + resource suffix stripping ---
+  // e.g., submitApplication -> submit, acceptOrigination -> accept
+  const actionVerbs = [
+    "submit",
+    "approve",
+    "reject",
+    "accept",
+    "cancel",
+    "start",
+    "stop",
+    "regenerate",
+    "rotate",
+    "activate",
+    "deactivate",
+    "release",
+    "simulate",
+    "upsert",
+  ];
+
+  for (const verb of actionVerbs) {
+    if (!action.startsWith(verb) || action === verb) continue;
+    const suffix = action.slice(verb.length);
+
+    if (suffix === singularRes || suffix === pluralRes) {
+      return { group, methodName: verb, confidence: "high" };
+    }
+
+    // Partial: suffix is tail of resource name (e.g., ApiKey on PlatformApiKeys)
+    if (singularRes.endsWith(suffix) || singularRes.endsWith(singularize(suffix))) {
+      return { group, methodName: verb, confidence: "high" };
+    }
+  }
+
+  // --- Fallback: use action as-is ---
+  return { group, methodName: toCamelCase(action), confidence: "low" };
+}
+
+// ---------------------------------------------------------------------------
+// 5. Generate overlay YAML block
+// ---------------------------------------------------------------------------
+function generateOverlayEntry(op: SpecOperation, naming: NamingResult): string {
+  const now = Date.now();
+  const controllerPart = op.operationId.slice(0, op.operationId.indexOf("_"));
+  const resourceName = controllerPart.replace(/Controller$/, "");
+
+  // Determine the "after" group name
+  const afterGroup = naming.group ?? toCamelCase(resourceName);
+  const afterStr = `sdk.${afterGroup}.${naming.methodName}()`;
+
+  // Determine the "before" group name (Speakeasy default: PascalCase with spaces)
+  const beforeGroup = toDisplayGroup(resourceName);
+  const beforeStr = `sdk.${beforeGroup}.${op.operationId}()`;
+
+  let yaml = `  - target: $["paths"]["${op.path}"]["${op.method}"]\n`;
+  yaml += `    update:\n`;
+  if (naming.group) {
+    yaml += `      x-speakeasy-group: ${naming.group}\n`;
+  }
+  yaml += `      x-speakeasy-name-override: ${naming.methodName}\n`;
+  yaml += `    x-speakeasy-metadata:\n`;
+  yaml += `      after: ${afterStr}\n`;
+  yaml += `      before: ${beforeStr}\n`;
+  yaml += `      created_at: ${now}\n`;
+  yaml += `      reviewed_at: ${now}\n`;
+  yaml += `      type: method-name`;
+
+  return yaml;
+}
+
+// ---------------------------------------------------------------------------
+// 6. Main
+// ---------------------------------------------------------------------------
+function main(): void {
+  const applyMode = process.argv.includes("--apply");
+
+  console.log("=== Speakeasy Overlay Fix ===\n");
+
+  // Extract operations from spec
+  const specOps = extractSpecOperations(SPEC_PATH);
+
+  // Extract covered operation IDs from overlay
+  const coveredIds = extractCoveredOperationIds(OVERLAY_PATH);
+
+  // Find uncovered operations
+  const uncoveredOps = specOps.filter(
+    (op) => !coveredIds.has(op.operationId)
+  );
+
+  if (uncoveredOps.length === 0) {
+    console.log("\nAll operations are already covered by the overlay. Nothing to do.");
+    return;
+  }
+
+  console.log(`\nFound ${uncoveredOps.length} uncovered operation(s):\n`);
+
+  // Generate overlay entries
+  const entries: OverlayEntry[] = uncoveredOps.map((op) => {
+    const naming = deriveNames(op.operationId);
+    const yamlBlock = generateOverlayEntry(op, naming);
+    return { operation: op, naming, yamlBlock };
+  });
+
+  // Display results grouped by confidence
+  const highConfidence = entries.filter((e) => e.naming.confidence === "high");
+  const lowConfidence = entries.filter((e) => e.naming.confidence === "low");
+
+  if (highConfidence.length > 0) {
+    console.log(`--- High confidence (${highConfidence.length}) ---`);
+    for (const entry of highConfidence) {
+      const groupStr = entry.naming.group
+        ? `[group: ${entry.naming.group}] `
+        : "";
+      console.log(
+        `  ${entry.operation.operationId} -> ${groupStr}${entry.naming.methodName}`
+      );
+    }
+    console.log();
+  }
+
+  if (lowConfidence.length > 0) {
+    console.log(`--- Needs review (${lowConfidence.length}) ---`);
+    for (const entry of lowConfidence) {
+      const groupStr = entry.naming.group
+        ? `[group: ${entry.naming.group}] `
+        : "";
+      console.log(
+        `  ${entry.operation.operationId} -> ${groupStr}${entry.naming.methodName}  <-- review this`
+      );
+    }
+    console.log();
+  }
+
+  if (!applyMode) {
+    console.log(
+      "Dry run complete. Run with --apply to write changes to the overlay file."
+    );
+    console.log(`  npx tsx scripts/fix-overlay.ts --apply\n`);
+
+    // Still show what would be written
+    console.log("--- Preview of new overlay entries ---\n");
+    for (const entry of entries) {
+      console.log(entry.yamlBlock);
+      console.log();
+    }
+    return;
+  }
+
+  // Apply changes
+  let overlayContent = readFileSync(OVERLAY_PATH, "utf8");
+
+  // Bump version
+  const currentVersion = getOverlayVersion(OVERLAY_PATH);
+  const newVersion = bumpPatchVersion(currentVersion);
+  overlayContent = overlayContent.replace(
+    `version: ${currentVersion}`,
+    `version: ${newVersion}`
+  );
+
+  // Append new entries (ensure trailing newline before appending)
+  if (!overlayContent.endsWith("\n")) {
+    overlayContent += "\n";
+  }
+
+  for (const entry of entries) {
+    overlayContent += entry.yamlBlock + "\n";
+  }
+
+  writeFileSync(OVERLAY_PATH, overlayContent, "utf8");
+
+  console.log(`Overlay updated: version ${currentVersion} -> ${newVersion}`);
+  console.log(`Added ${entries.length} new method-name entries.`);
+
+  if (lowConfidence.length > 0) {
+    console.log(
+      `\nWARNING: ${lowConfidence.length} entries need manual review (marked above).`
+    );
+    console.log(
+      "Edit .speakeasy/speakeasy-modifications-overlay.yaml to adjust before committing."
+    );
+  }
+
+  console.log("\nDone! Review changes with: git diff .speakeasy/speakeasy-modifications-overlay.yaml");
+}
+
+main();

package/src/funcs/billingCycleConfigsCreate.ts

@@ -0,0 +1,188 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { OatFiSDKCore } from "../core.js";
+import { encodeJSON, encodeSimple } from "../lib/encodings.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { OatFiSDKError } from "../models/errors/oatfisdkerror.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import * as models from "../models/index.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Create a billing cycle config
+ */
+export function billingCycleConfigsCreate(
+  client: OatFiSDKCore,
+  request:
+    operations.BillingCycleConfigsControllerCreateBillingCycleConfigRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    models.BillingCycleConfigsResponseDto,
+    | OatFiSDKError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: OatFiSDKCore,
+  request:
+    operations.BillingCycleConfigsControllerCreateBillingCycleConfigRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      models.BillingCycleConfigsResponseDto,
+      | OatFiSDKError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      operations
+        .BillingCycleConfigsControllerCreateBillingCycleConfigRequest$outboundSchema
+        .parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload.CreateBillingCycleConfigsDto, {
+    explode: true,
+  });
+
+  const pathParams = {
+    business: encodeSimple("business", payload.business, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path = pathToFunc("/v3/businesses/{business}/billing-cycle-configs")(
+    pathParams,
+  );
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "Idempotency-Key": encodeSimple(
+      "Idempotency-Key",
+      payload["Idempotency-Key"],
+      { explode: false, charEncoding: "none" },
+    ),
+  }));
+
+  const secConfig = await extractSecurity(client._options.bearer);
+  const securityInput = secConfig == null ? {} : { bearer: secConfig };
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "BillingCycleConfigsController_createBillingCycleConfig",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.bearer,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || {
+        strategy: "backoff",
+        backoff: {
+          initialInterval: 500,
+          maxInterval: 60000,
+          exponent: 1.5,
+          maxElapsedTime: 120000,
+        },
+        retryConnectionErrors: true,
+      }
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["5XX"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    errorCodes: ["400", "4XX", "5XX"],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const [result] = await M.match<
+    models.BillingCycleConfigsResponseDto,
+    | OatFiSDKError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(201, models.BillingCycleConfigsResponseDto$inboundSchema),
+    M.fail([400, "4XX"]),
+    M.fail("5XX"),
+  )(response, req);
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}