@sanity/cli 7.12.1 → 7.14.0

package/README.md

@@ -13,6 +13,7 @@ Code for sanity cli
 
   <!-- commands -->
 
+- [`sanity api ENDPOINT`](#sanity-api-endpoint)
 - [`sanity backups disable [DATASET]`](#sanity-backups-disable-dataset)
 - [`sanity backups download [DATASET]`](#sanity-backups-download-dataset)
 - [`sanity backups enable [DATASET]`](#sanity-backups-enable-dataset)
@@ -122,6 +123,93 @@ Code for sanity cli
 - [`sanity users list`](#sanity-users-list)
 - [`sanity versions`](#sanity-versions)
 
+## `sanity api ENDPOINT`
+
+Make an authenticated HTTP request to a Sanity API
+
+```
+USAGE
+  $ sanity api ENDPOINT [-p <id>] [-d <name>] [--api-version <version>] [--global | --project-hosted] [-H
+    <key:value>...] [-i] [--input <file> | -F <key=value>... | -f <key=value>...] [-X <method>] [--pretty] [-t <token> |
+    --anonymous]
+
+ARGUMENTS
+  ENDPOINT  API path (eg "projects" or "data/query/{dataset}"), optionally with placeholders, or a full
+            https://*.api.sanity.io URL
+
+FLAGS
+  -F, --field=<key=value>...      Add a typed parameter (key=value): true/false/null and numbers are converted, @file
+                                  reads the value from a file, @- from stdin
+  -H, --header=<key:value>...     Add an HTTP request header (key: value)
+  -X, --method=<method>           HTTP method to use (default GET, or POST when fields or --input are provided)
+  -f, --raw-field=<key=value>...  Add a string parameter (key=value)
+  -i, --include                   Include the HTTP response status and headers in the output
+  -t, --token=<token>             API token to authenticate with, instead of the logged-in user token
+      --anonymous                 Send the request without an authorization token
+      --api-version=<version>     API version to use (eg v2025-02-19). Defaults to a version embedded in the endpoint
+                                  path, or the version from the matching OpenAPI spec
+      --global                    Force the request to the global API host (api.sanity.io)
+      --input=<file>              Read the raw request body from a file (use "-" for stdin). Sent without a default
+                                  Content-Type - provide one with -H when the API requires it
+      --pretty                    Colorize JSON output
+      --project-hosted            Force the request to the project API host (<projectId>.api.sanity.io)
+
+OVERRIDE FLAGS
+  -d, --dataset=<name>   Dataset for {dataset} placeholders (overrides CLI configuration)
+  -p, --project-id=<id>  Project ID for {projectId} placeholders and project-hosted APIs (overrides CLI configuration)
+
+DESCRIPTION
+  Make an authenticated HTTP request to a Sanity API
+
+  The endpoint argument is an API path as documented in the published OpenAPI
+  specifications - list them with "sanity openapi list" and inspect one with
+  "sanity openapi get <slug>". Paths can be copied verbatim from the specs:
+  {projectId} and {dataset} placeholders are filled in from flags or the CLI
+  configuration, and the API host (api.sanity.io or <projectId>.api.sanity.io)
+  is chosen based on the specs' routing information.
+
+  The default request method is GET, or POST when fields or --input are
+  provided. For GET/HEAD requests, fields are sent as query parameters;
+  otherwise they are combined into a JSON request body sent with
+  "Content-Type: application/json". Raw --input bodies are sent without a
+  default Content-Type - provide one with -H when the API requires it. The
+  response body is written to stdout.
+
+  Requests are authenticated with the token from "sanity login". To use a
+  specific token instead - for example in CI or when the CLI is not logged in
+  - pass --token or set the SANITY_AUTH_TOKEN environment variable. Pass
+  --anonymous to send no token at all.
+
+EXAMPLES
+  Get the current user
+
+    $ sanity api users/me
+
+  Get the current project (placeholder filled from CLI config)
+
+    $ sanity api projects/{projectId}
+
+  Run a GROQ query against the project host
+
+    $ sanity api 'data/query/{dataset}' -f query='*[_type == "movie"][0..2]'
+
+  Send a JSON body built from typed fields
+
+    $ sanity api projects/{projectId} -X PATCH -F displayName="My project"
+
+  Send a raw request body from stdin
+
+    echo '{"mutations": []}' | sanity api 'data/mutate/{dataset}' --input - -H 'Content-Type: application/json'
+
+  Include the response status and headers, pinning the API version
+
+    $ sanity api jobs/123 --include --api-version v2025-02-19
+
+  Authenticate with a specific token instead of the logged-in session
+
+    SANITY_AUTH_TOKEN=<token> sanity api users/me
+```
+
 ## `sanity backups disable [DATASET]`
 
 Disable backup for a dataset

package/dist/actions/api/constants.js

@@ -0,0 +1,13 @@
+/**
+ * Fallback API version used when neither the endpoint path, the `--api-version`
+ * flag, nor the matched OpenAPI spec provides one.
+ */ export const API_DEFAULT_VERSION = 'v2025-02-19';
+/**
+ * Base URL for the published OpenAPI specification index.
+ * Also used by the `sanity openapi` commands.
+ */ export const OPENAPI_SPEC_INDEX_URL = 'https://www.sanity.io/docs/api/openapi';
+/**
+ * Matches an API version path segment: `v1`, `vX` or `v<YYYY-MM-DD>`.
+ */ export const API_VERSION_SEGMENT_RE = /^v(?:\d{4}-\d{2}-\d{2}|X|\d+)$/;
+
+//# sourceMappingURL=constants.js.map

package/dist/actions/api/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/api/constants.ts"],"sourcesContent":["/**\n * Fallback API version used when neither the endpoint path, the `--api-version`\n * flag, nor the matched OpenAPI spec provides one.\n */\nexport const API_DEFAULT_VERSION = 'v2025-02-19'\n\n/**\n * Base URL for the published OpenAPI specification index.\n * Also used by the `sanity openapi` commands.\n */\nexport const OPENAPI_SPEC_INDEX_URL = 'https://www.sanity.io/docs/api/openapi'\n\n/**\n * Matches an API version path segment: `v1`, `vX` or `v<YYYY-MM-DD>`.\n */\nexport const API_VERSION_SEGMENT_RE = /^v(?:\\d{4}-\\d{2}-\\d{2}|X|\\d+)$/\n"],"names":["API_DEFAULT_VERSION","OPENAPI_SPEC_INDEX_URL","API_VERSION_SEGMENT_RE"],"mappings":"AAAA;;;CAGC,GACD,OAAO,MAAMA,sBAAsB,cAAa;AAEhD;;;CAGC,GACD,OAAO,MAAMC,yBAAyB,yCAAwC;AAE9E;;CAEC,GACD,OAAO,MAAMC,yBAAyB,iCAAgC"}

package/dist/actions/api/distillApiRoutes.js

@@ -0,0 +1,106 @@
+import { API_VERSION_SEGMENT_RE } from './constants.js';
+/**
+ * Distill fetched OpenAPI specifications into the routing manifest used by
+ * `sanity api` to decide which host serves a request path and which API
+ * version to default to.
+ *
+ * The output is deterministic (sorted) so the generated manifest can be
+ * compared against a fresh distillation to detect drift.
+ */ export function distillApiRoutes(specs) {
+    const entries = [];
+    for (const { document, slug, title } of specs){
+        const servers = document.servers ?? [];
+        const paths = Object.keys(document.paths ?? {});
+        if (servers.length === 0 || paths.length === 0) continue;
+        // A spec may be served on both hosts (eg the Applications API). Emit one
+        // entry per host, each carrying the full set of path patterns.
+        const byHost = new Map();
+        for (const server of servers){
+            const base = parseServerUrl(server.url, server.variables);
+            if (!base) continue;
+            if (!byHost.has(base.host)) byHost.set(base.host, base);
+        }
+        for (const base of byHost.values()){
+            const patterns = new Set();
+            let defaultApiVersion = base.defaultApiVersion;
+            for (const path of paths){
+                const { segments, version } = normalizePathSegments(path);
+                defaultApiVersion = defaultApiVersion ?? version;
+                const pattern = [
+                    ...base.segments,
+                    ...segments
+                ].join('/');
+                if (pattern !== '') patterns.add(pattern);
+            }
+            if (patterns.size === 0) continue;
+            entries.push({
+                ...defaultApiVersion === undefined ? {} : {
+                    defaultApiVersion
+                },
+                host: base.host,
+                pathPatterns: [
+                    ...patterns
+                ].toSorted(),
+                slug,
+                title
+            });
+        }
+    }
+    return entries.toSorted((a, b)=>a.slug.localeCompare(b.slug) || a.host.localeCompare(b.host));
+}
+/**
+ * Parse an OpenAPI server URL template (eg
+ * `https://{projectId}.api.sanity.io/{apiVersion}/agent/action`) into a host
+ * classification, base path segments and a default API version.
+ *
+ * Returns `undefined` for URLs that don't look like a Sanity API host.
+ */ function parseServerUrl(url, variables) {
+    const withoutScheme = url.replace(/^https?:\/\//, '');
+    const [hostname = '', ...pathSegments] = withoutScheme.split('/');
+    if (!hostname.includes('api.sanity.io') && !hostname.includes('api.sanity.work')) {
+        return undefined;
+    }
+    const host = hostname.includes('{projectId}') ? 'project' : 'global';
+    let defaultApiVersion = normalizeVersion(variables?.apiVersion?.default);
+    const segments = [];
+    for (const segment of pathSegments){
+        if (segment === '') continue;
+        if (segment === '{apiVersion}') continue;
+        if (API_VERSION_SEGMENT_RE.test(segment)) {
+            defaultApiVersion = defaultApiVersion ?? segment;
+            continue;
+        }
+        segments.push(segment);
+    }
+    return {
+        defaultApiVersion,
+        host,
+        segments
+    };
+}
+/**
+ * Normalize an OpenAPI path template into version-less path segments, plus the
+ * API version if one was embedded in the path (eg `/v2024-07-01/access/...`).
+ *
+ * Some specs carry a stray query marker in the path key (eg `/foo/{id}?`) -
+ * anything from `?` on is not part of the path and is dropped.
+ */ function normalizePathSegments(path) {
+    const [pathPart = ''] = path.split('?');
+    const segments = pathPart.split('/').filter((segment)=>segment !== '');
+    let version;
+    if (segments[0] === '{apiVersion}') {
+        segments.shift();
+    } else if (segments.length > 0 && API_VERSION_SEGMENT_RE.test(segments[0])) {
+        version = segments.shift();
+    }
+    return {
+        segments,
+        version
+    };
+}
+function normalizeVersion(version) {
+    if (!version) return undefined;
+    return API_VERSION_SEGMENT_RE.test(version) ? version : undefined;
+}
+
+//# sourceMappingURL=distillApiRoutes.js.map

package/dist/actions/api/distillApiRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/api/distillApiRoutes.ts"],"sourcesContent":["import {API_VERSION_SEGMENT_RE} from './constants.js'\nimport {type ApiHost, type ApiRouteEntry, type OpenApiDocument} from './types.js'\n\n/**\n * A fetched OpenAPI specification, ready for distillation.\n */\nexport interface SpecSource {\n  document: OpenApiDocument\n  slug: string\n  title: string\n}\n\ninterface ServerBase {\n  host: ApiHost\n  segments: string[]\n\n  defaultApiVersion?: string\n}\n\n/**\n * Distill fetched OpenAPI specifications into the routing manifest used by\n * `sanity api` to decide which host serves a request path and which API\n * version to default to.\n *\n * The output is deterministic (sorted) so the generated manifest can be\n * compared against a fresh distillation to detect drift.\n */\nexport function distillApiRoutes(specs: SpecSource[]): ApiRouteEntry[] {\n  const entries: ApiRouteEntry[] = []\n\n  for (const {document, slug, title} of specs) {\n    const servers = document.servers ?? []\n    const paths = Object.keys(document.paths ?? {})\n    if (servers.length === 0 || paths.length === 0) continue\n\n    // A spec may be served on both hosts (eg the Applications API). Emit one\n    // entry per host, each carrying the full set of path patterns.\n    const byHost = new Map<ApiHost, ServerBase>()\n    for (const server of servers) {\n      const base = parseServerUrl(server.url, server.variables)\n      if (!base) continue\n      if (!byHost.has(base.host)) byHost.set(base.host, base)\n    }\n\n    for (const base of byHost.values()) {\n      const patterns = new Set<string>()\n      let defaultApiVersion = base.defaultApiVersion\n\n      for (const path of paths) {\n        const {segments, version} = normalizePathSegments(path)\n        defaultApiVersion = defaultApiVersion ?? version\n        const pattern = [...base.segments, ...segments].join('/')\n        if (pattern !== '') patterns.add(pattern)\n      }\n\n      if (patterns.size === 0) continue\n\n      entries.push({\n        ...(defaultApiVersion === undefined ? {} : {defaultApiVersion}),\n        host: base.host,\n        pathPatterns: [...patterns].toSorted(),\n        slug,\n        title,\n      })\n    }\n  }\n\n  return entries.toSorted((a, b) => a.slug.localeCompare(b.slug) || a.host.localeCompare(b.host))\n}\n\n/**\n * Parse an OpenAPI server URL template (eg\n * `https://{projectId}.api.sanity.io/{apiVersion}/agent/action`) into a host\n * classification, base path segments and a default API version.\n *\n * Returns `undefined` for URLs that don't look like a Sanity API host.\n */\nfunction parseServerUrl(\n  url: string,\n  variables?: Record<string, {default?: string}>,\n): ServerBase | undefined {\n  const withoutScheme = url.replace(/^https?:\\/\\//, '')\n  const [hostname = '', ...pathSegments] = withoutScheme.split('/')\n\n  if (!hostname.includes('api.sanity.io') && !hostname.includes('api.sanity.work')) {\n    return undefined\n  }\n\n  const host: ApiHost = hostname.includes('{projectId}') ? 'project' : 'global'\n\n  let defaultApiVersion = normalizeVersion(variables?.apiVersion?.default)\n  const segments: string[] = []\n  for (const segment of pathSegments) {\n    if (segment === '') continue\n    if (segment === '{apiVersion}') continue\n    if (API_VERSION_SEGMENT_RE.test(segment)) {\n      defaultApiVersion = defaultApiVersion ?? segment\n      continue\n    }\n    segments.push(segment)\n  }\n\n  return {defaultApiVersion, host, segments}\n}\n\n/**\n * Normalize an OpenAPI path template into version-less path segments, plus the\n * API version if one was embedded in the path (eg `/v2024-07-01/access/...`).\n *\n * Some specs carry a stray query marker in the path key (eg `/foo/{id}?`) -\n * anything from `?` on is not part of the path and is dropped.\n */\nfunction normalizePathSegments(path: string): {segments: string[]; version?: string} {\n  const [pathPart = ''] = path.split('?')\n  const segments = pathPart.split('/').filter((segment) => segment !== '')\n  let version: string | undefined\n\n  if (segments[0] === '{apiVersion}') {\n    segments.shift()\n  } else if (segments.length > 0 && API_VERSION_SEGMENT_RE.test(segments[0])) {\n    version = segments.shift()\n  }\n\n  return {segments, version}\n}\n\nfunction normalizeVersion(version: string | undefined): string | undefined {\n  if (!version) return undefined\n  return API_VERSION_SEGMENT_RE.test(version) ? version : undefined\n}\n"],"names":["API_VERSION_SEGMENT_RE","distillApiRoutes","specs","entries","document","slug","title","servers","paths","Object","keys","length","byHost","Map","server","base","parseServerUrl","url","variables","has","host","set","values","patterns","Set","defaultApiVersion","path","segments","version","normalizePathSegments","pattern","join","add","size","push","undefined","pathPatterns","toSorted","a","b","localeCompare","withoutScheme","replace","hostname","pathSegments","split","includes","normalizeVersion","apiVersion","default","segment","test","pathPart","filter","shift"],"mappings":"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"}

package/dist/actions/api/errors.js

@@ -0,0 +1,18 @@
+/**
+ * The user provided invalid input to `sanity api` (bad field syntax, missing
+ * placeholder values, unsupported host, ...). Mapped to exit code 2 by the
+ * command, per the CLI exit code convention.
+ */ export class ApiUsageError extends Error {
+}
+/**
+ * The request targets the project API host (or the path contains a
+ * `{projectId}` placeholder) but no project ID has been resolved yet. The
+ * command catches this to trigger project resolution (flag, CLI config or
+ * interactive prompt) and retries.
+ */ export class ProjectIdRequiredError extends Error {
+    constructor(){
+        super('A project ID is required for this request');
+    }
+}
+
+//# sourceMappingURL=errors.js.map

package/dist/actions/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/api/errors.ts"],"sourcesContent":["/**\n * The user provided invalid input to `sanity api` (bad field syntax, missing\n * placeholder values, unsupported host, ...). Mapped to exit code 2 by the\n * command, per the CLI exit code convention.\n */\nexport class ApiUsageError extends Error {}\n\n/**\n * The request targets the project API host (or the path contains a\n * `{projectId}` placeholder) but no project ID has been resolved yet. The\n * command catches this to trigger project resolution (flag, CLI config or\n * interactive prompt) and retries.\n */\nexport class ProjectIdRequiredError extends Error {\n  constructor() {\n    super('A project ID is required for this request')\n  }\n}\n"],"names":["ApiUsageError","Error","ProjectIdRequiredError"],"mappings":"AAAA;;;;CAIC,GACD,OAAO,MAAMA,sBAAsBC;AAAO;AAE1C;;;;;CAKC,GACD,OAAO,MAAMC,+BAA+BD;IAC1C,aAAc;QACZ,KAAK,CAAC;IACR;AACF"}

package/dist/actions/api/parseFields.js

@@ -0,0 +1,183 @@
+import { ApiUsageError } from './errors.js';
+const KEY_RE = /^([^=[\]]+)((?:\[[^[\]]*\])*)$/;
+/**
+ * Convert parsed fields to query parameters, for request methods without a
+ * body (GET/HEAD). Only scalar values (and arrays of scalars) are supported.
+ */ export function fieldsToQuery(fields) {
+    // Null-prototype for the same reason as in parseFields.
+    const query = Object.create(null);
+    for (const [key, value] of Object.entries(fields)){
+        if (Array.isArray(value)) {
+            if (value.some((item)=>typeof item === 'object' && item !== null)) {
+                throw new ApiUsageError(`Cannot use nested field "${key}" as a query parameter`);
+            }
+            query[key] = value.map(String);
+        } else if (typeof value === 'object' && value !== null) {
+            throw new ApiUsageError(`Cannot use nested field "${key}" as a query parameter`);
+        } else {
+            query[key] = String(value);
+        }
+    }
+    return query;
+}
+/**
+ * Parse `gh api`-style field flags into a JSON-compatible object.
+ *
+ * Supports nested keys with bracket syntax: `a[b]=1` produces `{a: {b: 1}}`,
+ * `a[]=1` appends to an array and a bare `a[]` declares an empty one.
+ * Raw fields (`-f`) keep values as strings; typed fields (`-F`) convert
+ * `true`/`false`/`null` and numbers, and expand `@<file>` / `@-` to file or
+ * stdin contents.
+ */ export function parseFields(options) {
+    const { fields = [], rawFields = [], readFile, stdin } = options;
+    // Null-prototype containers keep user-supplied keys like `__proto__` or
+    // `toString` ordinary own properties: nothing to pollute, nothing inherited.
+    const result = Object.create(null);
+    for (const raw of rawFields){
+        const { key, value } = splitField(raw, '--raw-field');
+        setField(result, key, value);
+    }
+    for (const field of fields){
+        const { key, value } = splitField(field, '--field');
+        setField(result, key, value === undefined ? undefined : coerceValue(value, {
+            flag: field,
+            readFile,
+            stdin
+        }));
+    }
+    return result;
+}
+function splitField(input, flagName) {
+    const separatorIndex = input.indexOf('=');
+    // A bare `key[]` without a value declares an empty array (gh api parity)
+    if (separatorIndex === -1 && input.endsWith('[]')) {
+        return {
+            key: input
+        };
+    }
+    if (separatorIndex < 1) {
+        throw new ApiUsageError(`Invalid ${flagName} "${input}": expected key=value format`);
+    }
+    return {
+        key: input.slice(0, separatorIndex),
+        value: input.slice(separatorIndex + 1)
+    };
+}
+function coerceValue(value, context) {
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+    if (value === 'null') return null;
+    if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+    if (value.startsWith('@')) {
+        const source = value.slice(1);
+        if (source === '-') {
+            if (context.stdin === undefined) {
+                throw new ApiUsageError(`Unable to read stdin for field "${context.flag}"`);
+            }
+            return context.stdin;
+        }
+        if (!context.readFile) {
+            throw new ApiUsageError(`Unable to read file for field "${context.flag}"`);
+        }
+        try {
+            return context.readFile(source);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ApiUsageError(`Failed to read "${source}" for field "${context.flag}": ${message}`);
+        }
+    }
+    return value;
+}
+/**
+ * Set a (possibly nested) field on the target object, `gh api`-style:
+ * `a=1` sets a top-level key, `a[b]=1` a nested object key, `a[]=1` appends
+ * to an array and a bare `a[]` declares an empty one (`value` is `undefined`).
+ *
+ * Array elements accumulate the way they do in gh: consecutive fields keep
+ * filling the current (last) element - `a[][k]=1 a[][j]=2` builds one object
+ * with both keys - until a key repeats, which starts the next element.
+ */ function setField(target, key, value) {
+    const match = KEY_RE.exec(key);
+    if (!match) {
+        throw new ApiUsageError(`Invalid field key "${key}"`);
+    }
+    const [, head, brackets] = match;
+    const path = [
+        head
+    ];
+    if (brackets) {
+        for (const part of brackets.matchAll(/\[([^[\]]*)\]/g)){
+            path.push(part[1]);
+        }
+    }
+    let container = target;
+    let subkey = '';
+    let inArray = false;
+    for (const segment of path){
+        if (segment === '') {
+            inArray = true;
+            continue;
+        }
+        if (subkey !== '') {
+            container = inArray ? descendIntoArray(container, subkey, segment, key) : descendIntoObject(container, subkey, key);
+            inArray = false;
+        }
+        subkey = segment;
+    }
+    if (inArray) {
+        const existing = Object.hasOwn(container, subkey) ? container[subkey] : undefined;
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new ApiUsageError(`Field "${key}" conflicts with an earlier field`);
+        }
+        const values = Array.isArray(existing) ? existing : [];
+        if (existing === undefined) {
+            container[subkey] = values;
+        }
+        if (value !== undefined) {
+            values.push(value);
+        }
+        return;
+    }
+    if (Object.hasOwn(container, subkey)) {
+        throw new ApiUsageError(`Field "${key}" conflicts with an earlier field`);
+    }
+    // A `value` of undefined only occurs for keys ending in `[]`, which take
+    // the array branch above.
+    container[subkey] = value;
+}
+/** Descend into (creating if needed) the object at `container[segment]`. */ function descendIntoObject(container, segment, key) {
+    const existing = Object.hasOwn(container, segment) ? container[segment] : undefined;
+    if (existing === undefined) {
+        const next = Object.create(null);
+        container[segment] = next;
+        return next;
+    }
+    if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+        throw new ApiUsageError(`Field "${key}" conflicts with an earlier field`);
+    }
+    return existing;
+}
+/**
+ * Descend into the array at `container[segment]`, returning the object
+ * element the field at hand should land in: the current (last) element while
+ * `nextKey` is new to it or accumulating a nested array, or a freshly
+ * appended element once `nextKey` repeats (gh api semantics).
+ */ function descendIntoArray(container, segment, nextKey, key) {
+    const existing = Object.hasOwn(container, segment) ? container[segment] : undefined;
+    if (existing !== undefined && !Array.isArray(existing)) {
+        throw new ApiUsageError(`Field "${key}" conflicts with an earlier field`);
+    }
+    const values = Array.isArray(existing) ? existing : [];
+    if (existing === undefined) {
+        container[segment] = values;
+    }
+    const last = values.at(-1);
+    if (typeof last === 'object' && last !== null && !Array.isArray(last) && (!Object.hasOwn(last, nextKey) || Array.isArray(last[nextKey]))) {
+        return last;
+    }
+    const next = Object.create(null);
+    values.push(next);
+    return next;
+}
+
+//# sourceMappingURL=parseFields.js.map

package/dist/actions/api/parseFields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/api/parseFields.ts"],"sourcesContent":["import {ApiUsageError} from './errors.js'\n\n/**\n * A JSON-compatible value produced by field parsing.\n */\nexport type FieldValue =\n  | boolean\n  | FieldValue[]\n  | number\n  | string\n  | {[key: string]: FieldValue}\n  | null\n\n/**\n * Options for {@link parseFields}.\n */\nexport interface ParseFieldsOptions {\n  /**\n   * Typed fields (`-F/--field`): `true`, `false`, `null` and numbers are\n   * converted; `@<file>` reads the value from a file, `@-` from stdin.\n   */\n  fields?: string[]\n\n  /** Raw string fields (`-f/--raw-field`): the value is used verbatim. */\n  rawFields?: string[]\n\n  /** Reads a file referenced via `@<file>`. */\n  readFile?: (path: string) => string\n\n  /** Content of stdin, for `@-` values. */\n  stdin?: string\n}\n\ntype FieldContainer = Record<string, FieldValue>\n\nconst KEY_RE = /^([^=[\\]]+)((?:\\[[^[\\]]*\\])*)$/\n\n/**\n * Convert parsed fields to query parameters, for request methods without a\n * body (GET/HEAD). Only scalar values (and arrays of scalars) are supported.\n */\nexport function fieldsToQuery(\n  fields: Record<string, FieldValue>,\n): Record<string, string | string[]> {\n  // Null-prototype for the same reason as in parseFields.\n  const query: Record<string, string | string[]> = Object.create(null)\n\n  for (const [key, value] of Object.entries(fields)) {\n    if (Array.isArray(value)) {\n      if (value.some((item) => typeof item === 'object' && item !== null)) {\n        throw new ApiUsageError(`Cannot use nested field \"${key}\" as a query parameter`)\n      }\n      query[key] = value.map(String)\n    } else if (typeof value === 'object' && value !== null) {\n      throw new ApiUsageError(`Cannot use nested field \"${key}\" as a query parameter`)\n    } else {\n      query[key] = String(value)\n    }\n  }\n\n  return query\n}\n\n/**\n * Parse `gh api`-style field flags into a JSON-compatible object.\n *\n * Supports nested keys with bracket syntax: `a[b]=1` produces `{a: {b: 1}}`,\n * `a[]=1` appends to an array and a bare `a[]` declares an empty one.\n * Raw fields (`-f`) keep values as strings; typed fields (`-F`) convert\n * `true`/`false`/`null` and numbers, and expand `@<file>` / `@-` to file or\n * stdin contents.\n */\nexport function parseFields(options: ParseFieldsOptions): Record<string, FieldValue> {\n  const {fields = [], rawFields = [], readFile, stdin} = options\n  // Null-prototype containers keep user-supplied keys like `__proto__` or\n  // `toString` ordinary own properties: nothing to pollute, nothing inherited.\n  const result: FieldContainer = Object.create(null)\n\n  for (const raw of rawFields) {\n    const {key, value} = splitField(raw, '--raw-field')\n    setField(result, key, value)\n  }\n\n  for (const field of fields) {\n    const {key, value} = splitField(field, '--field')\n    setField(\n      result,\n      key,\n      value === undefined ? undefined : coerceValue(value, {flag: field, readFile, stdin}),\n    )\n  }\n\n  return result\n}\n\nfunction splitField(input: string, flagName: string): {key: string; value?: string} {\n  const separatorIndex = input.indexOf('=')\n  // A bare `key[]` without a value declares an empty array (gh api parity)\n  if (separatorIndex === -1 && input.endsWith('[]')) {\n    return {key: input}\n  }\n  if (separatorIndex < 1) {\n    throw new ApiUsageError(`Invalid ${flagName} \"${input}\": expected key=value format`)\n  }\n  return {key: input.slice(0, separatorIndex), value: input.slice(separatorIndex + 1)}\n}\n\nfunction coerceValue(\n  value: string,\n  context: {flag: string; readFile?: (path: string) => string; stdin?: string},\n): FieldValue {\n  if (value === 'true') return true\n  if (value === 'false') return false\n  if (value === 'null') return null\n  if (/^-?\\d+(\\.\\d+)?$/.test(value)) return Number(value)\n\n  if (value.startsWith('@')) {\n    const source = value.slice(1)\n    if (source === '-') {\n      if (context.stdin === undefined) {\n        throw new ApiUsageError(`Unable to read stdin for field \"${context.flag}\"`)\n      }\n      return context.stdin\n    }\n    if (!context.readFile) {\n      throw new ApiUsageError(`Unable to read file for field \"${context.flag}\"`)\n    }\n    try {\n      return context.readFile(source)\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error)\n      throw new ApiUsageError(`Failed to read \"${source}\" for field \"${context.flag}\": ${message}`)\n    }\n  }\n\n  return value\n}\n\n/**\n * Set a (possibly nested) field on the target object, `gh api`-style:\n * `a=1` sets a top-level key, `a[b]=1` a nested object key, `a[]=1` appends\n * to an array and a bare `a[]` declares an empty one (`value` is `undefined`).\n *\n * Array elements accumulate the way they do in gh: consecutive fields keep\n * filling the current (last) element - `a[][k]=1 a[][j]=2` builds one object\n * with both keys - until a key repeats, which starts the next element.\n */\nfunction setField(target: FieldContainer, key: string, value: FieldValue | undefined): void {\n  const match = KEY_RE.exec(key)\n  if (!match) {\n    throw new ApiUsageError(`Invalid field key \"${key}\"`)\n  }\n\n  const [, head, brackets] = match\n  const path: string[] = [head]\n  if (brackets) {\n    for (const part of brackets.matchAll(/\\[([^[\\]]*)\\]/g)) {\n      path.push(part[1])\n    }\n  }\n\n  let container = target\n  let subkey = ''\n  let inArray = false\n  for (const segment of path) {\n    if (segment === '') {\n      inArray = true\n      continue\n    }\n    if (subkey !== '') {\n      container = inArray\n        ? descendIntoArray(container, subkey, segment, key)\n        : descendIntoObject(container, subkey, key)\n      inArray = false\n    }\n    subkey = segment\n  }\n\n  if (inArray) {\n    const existing = Object.hasOwn(container, subkey) ? container[subkey] : undefined\n    if (existing !== undefined && !Array.isArray(existing)) {\n      throw new ApiUsageError(`Field \"${key}\" conflicts with an earlier field`)\n    }\n    const values = Array.isArray(existing) ? existing : []\n    if (existing === undefined) {\n      container[subkey] = values\n    }\n    if (value !== undefined) {\n      values.push(value)\n    }\n    return\n  }\n\n  if (Object.hasOwn(container, subkey)) {\n    throw new ApiUsageError(`Field \"${key}\" conflicts with an earlier field`)\n  }\n  // A `value` of undefined only occurs for keys ending in `[]`, which take\n  // the array branch above.\n  container[subkey] = value as FieldValue\n}\n\n/** Descend into (creating if needed) the object at `container[segment]`. */\nfunction descendIntoObject(\n  container: FieldContainer,\n  segment: string,\n  key: string,\n): FieldContainer {\n  const existing = Object.hasOwn(container, segment) ? container[segment] : undefined\n  if (existing === undefined) {\n    const next: FieldContainer = Object.create(null)\n    container[segment] = next\n    return next\n  }\n  if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {\n    throw new ApiUsageError(`Field \"${key}\" conflicts with an earlier field`)\n  }\n  return existing\n}\n\n/**\n * Descend into the array at `container[segment]`, returning the object\n * element the field at hand should land in: the current (last) element while\n * `nextKey` is new to it or accumulating a nested array, or a freshly\n * appended element once `nextKey` repeats (gh api semantics).\n */\nfunction descendIntoArray(\n  container: FieldContainer,\n  segment: string,\n  nextKey: string,\n  key: string,\n): FieldContainer {\n  const existing = Object.hasOwn(container, segment) ? container[segment] : undefined\n  if (existing !== undefined && !Array.isArray(existing)) {\n    throw new ApiUsageError(`Field \"${key}\" conflicts with an earlier field`)\n  }\n  const values = Array.isArray(existing) ? existing : []\n  if (existing === undefined) {\n    container[segment] = values\n  }\n\n  const last = values.at(-1)\n  if (\n    typeof last === 'object' &&\n    last !== null &&\n    !Array.isArray(last) &&\n    (!Object.hasOwn(last, nextKey) || Array.isArray(last[nextKey]))\n  ) {\n    return last\n  }\n\n  const next: FieldContainer = Object.create(null)\n  values.push(next)\n  return next\n}\n"],"names":["ApiUsageError","KEY_RE","fieldsToQuery","fields","query","Object","create","key","value","entries","Array","isArray","some","item","map","String","parseFields","options","rawFields","readFile","stdin","result","raw","splitField","setField","field","undefined","coerceValue","flag","input","flagName","separatorIndex","indexOf","endsWith","slice","context","test","Number","startsWith","source","error","message","Error","target","match","exec","head","brackets","path","part","matchAll","push","container","subkey","inArray","segment","descendIntoArray","descendIntoObject","existing","hasOwn","values","next","nextKey","last","at"],"mappings":"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"}

package/dist/actions/api/resolveEndpoint.js

@@ -0,0 +1,159 @@
+import { parse } from 'node:querystring';
+import { API_DEFAULT_VERSION, API_VERSION_SEGMENT_RE } from './constants.js';
+import { ApiUsageError, ProjectIdRequiredError } from './errors.js';
+const PLACEHOLDER_RE = /^\{([^{}]+)\}$/;
+const ALLOWED_URL_HOST_RE = /(?:^|\.)api\.sanity\.(?:io|work)$/;
+/**
+ * Resolve the endpoint argument of `sanity api` into a concrete request
+ * target: substitute placeholders, split off the query string, determine the
+ * host family (via the generated OpenAPI routing manifest) and the API
+ * version.
+ *
+ * Throws {@link ProjectIdRequiredError} when the request needs a project ID
+ * that hasn't been provided - the command catches this to resolve one (flags,
+ * CLI config or interactive prompt) and retries.
+ */ export function resolveEndpoint(options) {
+    const { apiVersion, dataset, endpoint, forceHost, projectId, routes } = options;
+    if (/^https?:\/\//.test(endpoint)) {
+        return resolveUrlEndpoint(endpoint);
+    }
+    const [pathPart = '', ...queryParts] = endpoint.split('?');
+    const query = parseQueryString(queryParts.join('?'));
+    const segments = pathPart.split('/').filter((segment)=>segment !== '');
+    // An API version embedded in the path (eg `v2021-06-07/projects`) is peeled
+    // off and re-applied as the version segment of the final URL.
+    let embeddedVersion;
+    if (segments[0] === '{apiVersion}') {
+        segments.shift();
+    } else if (segments.length > 0 && API_VERSION_SEGMENT_RE.test(segments[0])) {
+        embeddedVersion = segments.shift();
+    }
+    // Checked after version peeling so a bare version (eg `v2025-02-19`) is
+    // also rejected as an empty path.
+    if (segments.length === 0) {
+        throw new ApiUsageError('Endpoint path is empty');
+    }
+    const unresolved = [];
+    const substituted = segments.map((segment, index)=>{
+        const placeholder = PLACEHOLDER_RE.exec(segment)?.[1];
+        if (!placeholder) return segment;
+        if (placeholder === 'projectId') {
+            if (!projectId) throw new ProjectIdRequiredError();
+            return projectId;
+        }
+        // The projects spec names the dataset placeholder `{name}` (eg
+        // `projects/{projectId}/datasets/{name}`) - only that context is a
+        // dataset; `{name}` elsewhere (eg video renditions) stays unresolved.
+        const isDatasetName = placeholder === 'name' && segments[index - 1] === 'datasets';
+        if (placeholder === 'dataset' || placeholder === 'datasetName' || isDatasetName) {
+            if (!dataset) {
+                throw new ApiUsageError(`Unable to resolve {${placeholder}} - provide a dataset with --dataset or configure one in sanity.cli.ts`);
+            }
+            return dataset;
+        }
+        unresolved.push(segment);
+        return segment;
+    });
+    if (unresolved.length > 0) {
+        throw new ApiUsageError(`Unable to resolve placeholder(s) ${unresolved.join(', ')} - replace them with actual values`);
+    }
+    // Forcing a host restricts matching to specs served on that host, so the
+    // matched spec's default API version still applies when one exists there.
+    const candidates = forceHost ? routes.filter((entry)=>entry.host === forceHost) : routes;
+    const match = matchRoutes(substituted, candidates);
+    const host = forceHost ?? match?.host ?? 'global';
+    if (host === 'project' && !projectId) {
+        throw new ProjectIdRequiredError();
+    }
+    return {
+        apiVersion: apiVersion ?? embeddedVersion ?? match?.defaultApiVersion ?? API_DEFAULT_VERSION,
+        host,
+        kind: 'path',
+        matchedSlug: match?.slug,
+        path: substituted.join('/'),
+        ...host === 'project' ? {
+            projectId
+        } : {},
+        query
+    };
+}
+function resolveUrlEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    } catch  {
+        throw new ApiUsageError(`Invalid URL "${endpoint}"`);
+    }
+    // Never put the token on the wire unencrypted
+    if (url.protocol !== 'https:') {
+        throw new ApiUsageError(`Refusing to send requests over "${url.protocol}//" - only https:// URLs are supported`);
+    }
+    if (!ALLOWED_URL_HOST_RE.test(url.hostname)) {
+        throw new ApiUsageError(`Refusing to send authenticated requests to "${url.hostname}" - only *.api.sanity.io hosts are supported`);
+    }
+    const query = parseQueryString(url.search.replace(/^\?/, ''));
+    url.search = '';
+    return {
+        kind: 'url',
+        query,
+        url: url.toString()
+    };
+}
+/**
+ * Find the route entry whose path pattern best matches the request segments.
+ *
+ * A pattern only matches when the request path consumes it completely, and
+ * segments are compared pairwise: literal matches score higher than
+ * placeholder matches, and a literal mismatch disqualifies the pattern. On
+ * equal scores across hosts the global host wins (APIs served on both hosts
+ * don't need a project ID there); on equal scores within the same host the
+ * first entry wins, keeping the result independent of later entries.
+ */ function matchRoutes(segments, routes) {
+    let best;
+    for (const entry of routes){
+        for (const pattern of entry.pathPatterns){
+            const score = scorePattern(segments, pattern.split('/'));
+            if (score === 0) continue;
+            const isBetter = !best || score > best.score || score === best.score && best.host === 'project' && entry.host === 'global';
+            if (isBetter) {
+                best = {
+                    defaultApiVersion: entry.defaultApiVersion,
+                    host: entry.host,
+                    score,
+                    slug: entry.slug
+                };
+            }
+        }
+    }
+    return best;
+}
+function scorePattern(segments, patternSegments) {
+    // A pattern only matches when the request path consumes it completely - a
+    // request that is a mere prefix of a longer pattern (eg `data` vs
+    // `data/query/{dataset}`) must not inherit that route's host or version.
+    if (patternSegments.length > segments.length) return 0;
+    let score = 0;
+    let literalMatches = 0;
+    for (const [index, patternSegment] of patternSegments.entries()){
+        if (PLACEHOLDER_RE.test(patternSegment)) {
+            score += 1;
+        } else if (patternSegment === segments[index]) {
+            score += 2;
+            literalMatches += 1;
+        } else {
+            return 0;
+        }
+    }
+    // Require at least one literal segment match so a placeholder-only pattern
+    // like `{resourceType}/{resourceId}` can't capture arbitrary paths.
+    return literalMatches === 0 ? 0 : score;
+}
+function parseQueryString(queryString) {
+    // node:querystring collects repeated keys into arrays and returns a
+    // null-prototype object, so user-supplied keys like `__proto__` stay
+    // ordinary own properties. Parsed values are never `undefined`, hence the
+    // narrowing cast.
+    return parse(queryString);
+}
+
+//# sourceMappingURL=resolveEndpoint.js.map