@propper-ai/cli 0.4.0 → 0.5.0

package/README.md

@@ -149,6 +149,7 @@ its help.
 Hand-authored:
 
 ```
+propper api          <path-or-url>   raw HTTP escape hatch (see below)
 propper auth         login | logout | status (whoami) | export [--unmasked]
 propper configure    [wizard] | set | get | list-profiles
 propper completion   bash | zsh | fish
@@ -179,6 +180,41 @@ propper sign documents upload --agreement-id ag_123 --file ./contract.pdf --file
 echo '{"name":"MSA"}' | propper sign agreements create --input-json -
 ```
 
+### Raw API access
+
+`propper api` is an escape hatch for endpoints not yet surfaced as commands —
+modeled on `gh api`. It reuses your stored credentials, `--query`/`--output`,
+and the standard error handling.
+
+```bash
+# GET (path resolved against the API base URL; auth attached automatically)
+propper api /v1/sign/agreements
+
+# query params travel in the path; JMESPath + table output still apply
+propper api "/v1/sign/agreements?limit=10" --query "[].id" --output table
+
+# custom method + JSON body (method defaults to POST when a body is supplied)
+propper api -X POST /v1/sign/agreements --input-json '{"name":"MSA"}'
+echo '{"name":"MSA"}' | propper api /v1/sign/agreements --input-json -
+
+# custom headers (repeatable); -i shows the status line + response headers
+propper api -i -H "X-Trace-Id: abc" /v1/sign/agreements
+
+# follow pagination and concatenate the results
+propper api --paginate /v1/sign/agreements
+```
+
+Flags: `-X, --method`, `-H, --header "Key: Value"` (repeatable; `"Key:"` removes
+a default header), `--input-json <json|@file|->`, `-i, --include`, `--paginate`,
+plus all global options.
+
+- An absolute `http(s)://` URL is used as-is; otherwise the path is resolved
+  against `--base-url` (default `https://api.propper.ai`).
+- Your stored bearer token is attached automatically. Supply your own
+  `-H "Authorization: …"` to override it (no login required).
+- JSON responses are formatted (so `--query`/`--output` apply); other content
+  types are written through unchanged.
+
 ## Use as a library (SDK)
 
 The generated client is API-namespaced and exported as `@propper-ai/cli/generated/client`:

package/dist/bin/propper.js

@@ -4,8 +4,9 @@ import {
   AuthError,
   UsageError,
   callOperation,
-  manifest
-} from "../chunk-XSRXBEWN.js";
+  manifest,
+  rawRequest
+} from "../chunk-K664LS27.js";
 
 // src/bin/propper.ts
 import { CommanderError } from "commander";
@@ -235,7 +236,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@propper-ai/cli",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "Propper CLI \u2014 an AWS-style, OpenAPI-generated command-line interface for the Propper Sign + Auth APIs",
   type: "module",
   license: "MIT",
@@ -623,6 +624,147 @@ async function resolveToken(ctx) {
   );
 }
 
+// src/runtime/input.ts
+import { readFileSync as readFileSync3 } from "fs";
+var defaultInputDeps = {
+  readFile: (path) => readFileSync3(path),
+  readStdin: () => readFileSync3(0, "utf8")
+};
+function resolveInput(raw, deps = defaultInputDeps) {
+  if (raw === "-") return deps.readStdin();
+  if (raw.startsWith("@")) return deps.readFile(raw.slice(1)).toString("utf8");
+  return raw;
+}
+function readInputJson(raw, deps = defaultInputDeps) {
+  const text = resolveInput(raw, deps);
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new UsageError(`--input-json is not valid JSON: ${err.message}`);
+  }
+}
+
+// src/runtime/pagination.ts
+var MAX_PAGES = 50;
+function pageItems(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") {
+    for (const key of ["data", "items", "results", "agreements", "templates", "recipients"]) {
+      const value = data[key];
+      if (Array.isArray(value)) return value;
+    }
+  }
+  return void 0;
+}
+
+// src/commands/api/index.ts
+var defaultApiDeps = {
+  resolveToken,
+  rawRequest,
+  input: defaultInputDeps,
+  stdout: process.stdout
+};
+function resolveUrl(pathOrUrl, baseUrl) {
+  if (/^https?:\/\//i.test(pathOrUrl)) return new URL(pathOrUrl);
+  return new URL(pathOrUrl.replace(/^\//, ""), `${baseUrl.replace(/\/$/, "")}/`);
+}
+function parseHeaders(raw) {
+  const headers = {};
+  for (const item of raw ?? []) {
+    const idx = item.indexOf(":");
+    if (idx === -1) throw new UsageError(`Invalid header "${item}" \u2014 expected "Key: Value"`);
+    const key = item.slice(0, idx).trim();
+    if (!key) throw new UsageError(`Invalid header "${item}" \u2014 missing name`);
+    headers[key] = item.slice(idx + 1).trim();
+  }
+  return headers;
+}
+function hasHeader(headers, name) {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+function printInclude(res, out) {
+  out.write(`HTTP ${res.status}
+`);
+  for (const [key, value] of res.headers.entries()) out.write(`${key}: ${value}
+`);
+  out.write("\n");
+}
+function printBody(res, ctx, out) {
+  if (res.bytes.length === 0) return;
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType === "" || /json/i.test(contentType)) {
+    const text = res.bytes.toString("utf8");
+    try {
+      printResult(JSON.parse(text), { output: ctx.output, query: ctx.query }, out);
+      return;
+    } catch {
+    }
+  }
+  out.write(res.bytes);
+}
+async function runApi(pathOrUrl, opts, ctx, deps = defaultApiDeps) {
+  const headers = parseHeaders(opts.header);
+  let body;
+  if (typeof opts.inputJson === "string") {
+    body = JSON.stringify(readInputJson(opts.inputJson, deps.input));
+    if (!hasHeader(headers, "content-type")) headers["content-type"] = "application/json";
+  }
+  const method = (opts.method ?? (body !== void 0 ? "POST" : "GET")).toUpperCase();
+  let token;
+  if (!hasHeader(headers, "authorization")) {
+    token = await deps.resolveToken({
+      explicitToken: ctx.explicitToken,
+      profile: ctx.profile,
+      authBaseUrl: ctx.authBaseUrl,
+      clientId: ctx.clientId,
+      clientSecret: ctx.clientSecret,
+      env: ctx.env
+    });
+  }
+  const reqCtx = {
+    apiBaseUrl: ctx.apiBaseUrl,
+    token,
+    userAgent: USER_AGENT,
+    debug: ctx.debug
+  };
+  const url = resolveUrl(pathOrUrl, ctx.apiBaseUrl);
+  const errorMeta = { method, path: pathOrUrl };
+  if (opts.paginate) {
+    const collected = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      url.searchParams.set("page", String(page));
+      const res2 = await deps.rawRequest(
+        method,
+        url.toString(),
+        { headers, body },
+        reqCtx,
+        errorMeta
+      );
+      let data;
+      try {
+        const text = res2.bytes.toString("utf8");
+        data = text ? JSON.parse(text) : void 0;
+      } catch {
+        throw new UsageError("--paginate requires a JSON response");
+      }
+      const items = pageItems(data);
+      if (!items) {
+        throw new UsageError("--paginate requires a JSON array or paged-envelope response");
+      }
+      if (items.length === 0) break;
+      collected.push(...items);
+      const limit = Number(url.searchParams.get("limit") ?? items.length);
+      if (items.length < limit) break;
+    }
+    printResult(collected, { output: ctx.output, query: ctx.query }, deps.stdout);
+    return;
+  }
+  const res = await deps.rawRequest(method, url.toString(), { headers, body }, reqCtx, errorMeta);
+  if (opts.include) printInclude(res, deps.stdout);
+  printBody(res, ctx, deps.stdout);
+}
+
 // src/commands/auth/deps.ts
 var defaultAuthDeps = {
   resolveToken,
@@ -900,7 +1042,10 @@ var GLOBAL_FLAGS = [
 var STATIC_GROUPS = {
   auth: ["login", "logout", "status", "whoami", "export"],
   configure: ["set", "get", "list-profiles"],
-  completion: [...SUPPORTED_SHELLS]
+  completion: [...SUPPORTED_SHELLS],
+  // `api <path>` takes a freeform path argument, so there are no sub-candidates;
+  // an empty list still surfaces `api` itself at the top level.
+  api: []
 };
 function operationFlags(entry) {
   const flags = [
@@ -1083,7 +1228,7 @@ async function runConfigureWizard(ctx, input = process.stdin, output = process.s
 
 // src/runtime/dispatch.ts
 import { Buffer } from "buffer";
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 
 // src/manifest/types.ts
 function kebabCase(input) {
@@ -1130,7 +1275,7 @@ function flagKey(flag) {
 var defaultDispatchDeps = {
   resolveToken,
   call: (entry, req, ctx) => callOperation(entry.api, entry.operationId, req, ctx),
-  readFile: (path) => readFileSync3(path),
+  readFile: (path) => readFileSync4(path),
   writeFile: (path, data) => writeFileSync3(path, data),
   stdout: process.stdout
 };
@@ -1139,14 +1284,6 @@ function coerce(value, type) {
   if (type === "number" || type === "integer") return Number(value);
   return String(value);
 }
-function readInputJson(raw, deps) {
-  const text = raw === "-" ? readFileSync3(0, "utf8") : raw.startsWith("@") ? deps.readFile(raw.slice(1)).toString("utf8") : raw;
-  try {
-    return JSON.parse(text);
-  } catch (err) {
-    throw new UsageError(`--input-json is not valid JSON: ${err.message}`);
-  }
-}
 function buildRequest(entry, flags, deps) {
   const pathParams = {};
   for (const p of entry.pathParams) {
@@ -1165,7 +1302,13 @@ function buildRequest(entry, flags, deps) {
   if (entry.hasBody) {
     body = {};
     const inputJson = flags.inputJson;
-    if (typeof inputJson === "string") Object.assign(body, readInputJson(inputJson, deps));
+    if (typeof inputJson === "string") {
+      const parsed = readInputJson(inputJson, {
+        readFile: deps.readFile,
+        readStdin: defaultInputDeps.readStdin
+      });
+      Object.assign(body, parsed);
+    }
     for (const field of entry.bodyFields) {
       const value = flags[flagKey(field.flag)];
       if (value !== void 0) body[field.name] = coerce(value, field.type);
@@ -1177,17 +1320,6 @@ function buildRequest(entry, flags, deps) {
   }
   return { pathParams, query, body };
 }
-function pageItems(data) {
-  if (Array.isArray(data)) return data;
-  if (data && typeof data === "object") {
-    for (const key of ["data", "items", "results", "agreements", "templates", "recipients"]) {
-      const value = data[key];
-      if (Array.isArray(value)) return value;
-    }
-  }
-  return void 0;
-}
-var MAX_PAGES = 50;
 async function dispatch(entry, flags, ctx, deps = defaultDispatchDeps) {
   const token = await deps.resolveToken({
     explicitToken: ctx.explicitToken,
@@ -1245,6 +1377,9 @@ var defaultProgramDeps = {
     configureGet,
     configureListProfiles,
     runConfigureWizard
+  },
+  api: {
+    runApi
   }
 };
 function addGlobalOptions(cmd) {
@@ -1338,6 +1473,20 @@ function registerApiTopics(program, manifest2, deps) {
     addApiCommand(topicCmd, entry, deps);
   }
 }
+function registerApi(program, deps) {
+  const collect = (value, prev = []) => prev.concat(value);
+  addGlobalOptions(program.command("api")).argument("<path>", "Request path (resolved against the API base URL) or a full http(s) URL").description("Call an arbitrary Propper API endpoint (raw HTTP escape hatch)").option("-X, --method <verb>", "HTTP method (default GET, or POST when a body is supplied)").option(
+    "-H, --header <header>",
+    "Header as 'Key: Value' (repeatable; 'Key:' removes a default header)",
+    collect
+  ).option(
+    "--input-json <json|@file>",
+    "JSON request body: a string, @file.json, or '-' for stdin"
+  ).option("-i, --include", "Print the response status line and headers before the body").option("--paginate", "Auto-follow pages and concatenate the results").action(async (path, _opts, c) => {
+    const ctx = deps.buildContext(c.optsWithGlobals());
+    await deps.api.runApi(path, c.opts(), ctx);
+  });
+}
 function registerAuth(program, deps) {
   const auth = program.command("auth").description("Authenticate with Propper");
   showHelpWhenEmpty(auth);
@@ -1433,6 +1582,7 @@ function buildProgram(manifest2, deps = defaultProgramDeps) {
   program.addHelpText("after", `
 ${renderEnvHelp()}`);
   registerApiTopics(program, manifest2, deps);
+  registerApi(program, deps);
   registerAuth(program, deps);
   registerConfigure(program, deps);
   registerCompletion(program, manifest2);