@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/remote.d.ts

@@ -1,58 +1,163 @@
 /**
- * Talk to a REMOTE resolver's admin control plane — the HTTP form of `abx add` /
- * `abx index` / `abx forget`, pointed at a hosted node (fly/render/vps) instead of
- * this machine's local projection. This is the bridge the toolkit was missing: a
- * contract you deploy here is registered with the *local* store; the resolver baked
- * into your on-chain tokenURI is a *different* store and must be told separately, or
- * it answers "unknown project". These helpers do the telling.
+ * Remote-resolver resolution — which service `--remote` means, and whose credential drives it.
+ * The HTTP client itself lives in the SDK (`AbxServiceClient`, speaking the /v1 control plane from
+ * site/content/docs/using-abx/remote-services.mdx); this module owns the CLI conventions around it:
  *
- * The admin token authorizes indexing control only — never on-chain signing — so the
- * "no signing key on the host" rule is intact. It lives in `.env` as
- * ABX_RESOLVER_ADMIN_TOKEN and must match the token set on the resolver.
- */
-export interface RemoteAddBody {
-    address: string;
-    /** Scan floor — the deploy block. Omit on a re-POST (the nudge) to keep the stored floor + reindex incrementally. */
-    fromBlock?: string;
-    factory?: string;
-    label?: string;
-    description?: string;
-    externalUrl?: string;
-    /** Off-chain operator traits (OpenSea attribute array) — stitched UNDER any on-chain `attributes`. */
-    attributes?: Array<{
-        trait_type: string;
-        value: string | number;
-        display_type?: string;
-    }>;
-    /** Off-chain PER-TOKEN operator traits, `{ "<tokenId>": OpenSeaAttribute[] }` — a Series' editable
-     *  traits (a token's entry wins over the collection-scope `attributes`; on-chain wins over both). */
-    tokenAttributes?: Record<string, Array<{
-        trait_type: string;
-        value: string | number;
-        display_type?: string;
-    }>>;
-    /** Durable locators keyed by on-chain hash, `{ "0x<keccak>": "ipfs://<cid>" }` — lets the resolver
-     *  point `image` at IPFS/Arweave without holding the bytes. Merged over any already stored. */
-    contentLocators?: Record<string, string>;
-    /** Force a full replay even on a re-POST. */
-    full?: boolean;
+ *   --remote <name>   a NAMED remote — `ABX_REMOTE_<NAME>_URL` + `ABX_REMOTE_<NAME>_TOKEN` in .env
+ *                     (same env-name normalization as ABX_RPC_URLS_<CHAIN>). "self" is just a name
+ *                     under this SAME convention — the node YOU run reads ABX_REMOTE_SELF_URL/_TOKEN
+ *                     with zero special-casing below. A managed provider's per-account API key lives
+ *                     under its own name — and deliberately NEVER falls back to ABX_REMOTE_SELF_TOKEN,
+ *                     so your node-admin secret can't silently go to a third party.
+ *                     `abx` is the built-in first-party name: https://services.abx.io plus
+ *                     ABX_SERVICES_API_KEY. It needs no URL pasted into project configuration.
+ *   --remote <url>    an ad-hoc URL — token from --remote-token or ABX_REMOTE_SELF_TOKEN (the local
+ *                     client credential for a node you run; `abx deploy-resolver` generates it).
+ *   --remote          bare: the self-host default — ABX_PUBLIC_BASE_URL (the URL baked on-chain,
+ *                     else ABX_RESOLVER_URL) + ABX_REMOTE_SELF_TOKEN.
+ *
+ * Every token here authorizes indexing/metadata control only — never on-chain signing — so the
+ * "no signing key on the host" rule is intact. (`--remote-token`, not `--token`: `--token` already
+ * means a token ID across the owner ops.)
+ *
+ * The RESOLVER's own env var — what gates ITS control plane, server-side (packages/token-api/src/
+ * control-plane.ts) — is unchanged: still `ABX_RESOLVER_ADMIN_TOKEN`. Only the CLIENT-side lookup
+ * for a self-run node moved to the named-remote grammar above; `abx deploy-resolver` prints the exact
+ * command that carries the value across the name boundary (fly secrets set ABX_RESOLVER_ADMIN_TOKEN
+ * from your local ABX_REMOTE_SELF_TOKEN).
+ */
+import { AbxServiceClient, type Address, type IndexError, type IndexErrorClass, type IndexStatus, type ProvenanceResult, type RegisterProjectResult, type RemoteProjectStatus } from '@artblocks/abx-sdk';
+import { type Flags } from './flags.js';
+export declare const ABX_SERVICES_URL = "https://services.abx.io";
+export declare const ABX_SERVICES_API_KEY_VAR = "ABX_SERVICES_API_KEY";
+export type RemoteSource = 'url' | 'named' | 'builtin' | 'default';
+export interface RemoteTarget {
+    /** Base URL, trailing slashes stripped. */
+    url: string;
+    token?: string;
+    /** The normalized remote name (named form only). */
+    name?: string;
+    source: RemoteSource;
+    /** The env var that should hold this target's token — every error/skip message names it. */
+    tokenVar: string;
+    /** WHERE the token in hand actually came from. A 401 that blames the env var when the caller
+     *  passed `--remote-token` makes the override look ignored — which is exactly the moment someone
+     *  is testing a replacement key. */
+    tokenFrom?: 'flag' | 'env';
 }
-export interface RemoteAddResult {
+/** How to refer to the credential this target is using, in an error the creator has to act on. */
+export declare function tokenSourceLabel(t: RemoteTarget): string;
+/**
+ * Resolve the `--remote` flag value (undefined = local op → null). Pure: pass `env` in tests.
+ * `tokenFlag` is `--remote-token` and wins over any env token for this invocation.
+ */
+export declare function resolveRemote(spec: string | undefined, tokenFlag?: string, env?: NodeJS.ProcessEnv): RemoteTarget | null;
+/**
+ * The OLD client-side var (`ABX_RESOLVER_ADMIN_TOKEN`) sitting unused in `.env` because the
+ * self-host default's credential moved to the named-remote grammar (`ABX_REMOTE_SELF_TOKEN`) — a
+ * silent fallback would mean an operator's `.env` never gets renamed, so this is the ONE place both
+ * {@link requireRemoteToken} (the hard-stop for a real command) and `abx doctor` (the same fault,
+ * surfaced before a command needs it) decide whether to flag it — sharing the check means they can
+ * never drift on the condition. `null` when there's nothing to flag (old var absent, or the new one
+ * is already set and simply wins).
+ */
+export declare function selfTokenMigrationWarning(env?: NodeJS.ProcessEnv): string | null;
+/** The token, when the remote is the command's OBJECT (add/index/forget/render/migrate-dest) —
+ *  a missing credential is a hard stop that names the exact var to set. */
+export declare function requireRemoteToken(t: RemoteTarget, env?: NodeJS.ProcessEnv): string;
+/** Every named remote configured in the env (`ABX_REMOTE_<NAME>_URL`). The normalized name is
+ *  canonical — the env convention is lossy, so enumeration reads the env, never inverts it. */
+export declare function listConfiguredRemotes(env?: NodeJS.ProcessEnv): Array<{
+    name: string;
+    url: string;
+    hasToken: boolean;
+}>;
+/**
+ * `ABX_REMOTE_*` vars that follow no recognized suffix — i.e. a typo. The convention has exactly two
+ * suffixes (`_URL`, `_TOKEN`), and anything else (`_KEY`, `_APIKEY`, `_SECRET`) is silently ignored:
+ * the CLI reports "no token" while the value sits right there in `.env`. Cheap to detect, so detect
+ * it rather than leaving the creator to compare strings by eye.
+ */
+export declare function misnamedRemoteVars(env?: NodeJS.ProcessEnv): Array<{
+    key: string;
+    suggestion: string;
+}>;
+/** The SDK service client bound to this target (call {@link requireRemoteToken} first when the
+ *  operation needs auth). */
+export declare function serviceClient(t: RemoteTarget): AbxServiceClient;
+/**
+ * Is this named remote's stored credential actually accepted? One cheap authed read, so `doctor` can
+ * report capability instead of mere presence.
+ *
+ * Doctor is the command a creator runs FIRST, and it used to print a clean `remotes: meridian` for a
+ * key the service rejects — the 401 only surfaced later, from `abx remote <name>`, after they had
+ * already trusted the line. Same class as an RPC that answers `[]` because it pruned its logs: an
+ * empty success is not evidence of capability.
+ *
+ * Never throws and never blocks doctor for long: a short per-attempt timeout, and anything that is
+ * not a definitive rejection is reported as a soft note rather than a ✗, because a slow or briefly
+ * unreachable provider is not a misconfiguration the creator can act on.
+ */
+export declare function probeRemoteCredential(name: string, timeoutMs?: number): Promise<{
     ok: boolean;
-    mode: 'full' | 'incremental';
-    elapsedMs: number;
-    project: {
-        address: string;
-        name: string | null;
-        eventCount: number;
-        tokenCount: number;
-        mintedCount: number;
+    fatal: boolean;
+    detail: string;
+}>;
+/** The env var a named remote's token is read from — the one to name when it is rejected. */
+export declare function tokenVarFor(name: string): string;
+/**
+ * Map a control-plane failure to an actionable CLI error. Keys off `AbxServiceError.code`/status,
+ * never off message prose (the machine-code half of the interface spec):
+ *   401 — the credential itself was rejected → name the var that supplied it.
+ *   403 — credential fine, not authorized for this resource → provider scoping, don't retry.
+ *   `disabled` — the node has no control-plane token configured at all.
+ *   bare 404 on /v1 — no control plane at this URL (pre-/v1 node, or not an ABX service).
+ */
+export declare function describeRemoteError(err: unknown, t: RemoteTarget, label: string): Error;
+export declare function remoteFlag(flags: Flags): RemoteTarget | null;
+/**
+ * The factory-verification tri-state, said plainly. `null` means the check never ran (no factory
+ * configured, or the configured one has no code on this chain — common on a local/dev chain), which
+ * is NOT the same as the chain telling us this contract isn't a clone of it.
+ */
+export declare function canonicalLabel(isCanonical: boolean | null | undefined, provenance?: ProvenanceResult): string;
+/** How a lifecycle state reads at a glance — the same word everywhere it's printed. */
+export declare function statusLabel(s: IndexStatus): string;
+/** `label   value` with only the label dimmed — status values carry their own color, and wrapping
+ *  them in `info()` would fight it. */
+export declare const statusRow: (label: string, value: string) => void;
+/**
+ * What to DO about a failure class — whose problem it is and whether waiting is the answer.
+ * The class alone told an agent enough to reason it out; it does not tell a creator, and "whose
+ * problem is this" is the single question a failed catch-up has to answer.
+ */
+export declare function indexErrorAction(cls: IndexErrorClass): string;
+/** The one wording for "registered, but catch-up failed" — shared by add/index so both say the same
+ *  thing: what failed, whose problem it is, and that the registration survived. */
+export declare function failedCatchUpMessage(address: Address, remote: RemoteTarget, err: IndexError | undefined, check: string): string;
+/**
+ * One human line for a status read: where it is, how far along, and why if it's unhappy.
+ *
+ * What "where" means depends on the state, so say the right thing rather than one number that reads
+ * differently in each: a percentage is only honest while BACKFILLING (see indexProgress). A `live`
+ * project's `toBlock` only advances when that project has events, so on a busy chain a perfectly
+ * current project sits far below head — printing that as a ratio makes healthy look broken.
+ */
+export declare function statusLine(s: RemoteProjectStatus): string;
+/**
+ * Report a register/reindex answer, whichever of the two conformant shapes the service used.
+ *
+ * A `200` already carries the counts. A `202` means the registration is durable and catch-up is still
+ * running — so by default we poll to a terminal state and print the SAME summary line, giving the
+ * human the "waits, then tells you what happened" UX without the service holding a socket open for
+ * minutes. `--no-wait` stops at the 202 and names the command that checks later.
+ */
+export declare function reportRemoteIndexing(remote: RemoteTarget, chainId: number, address: Address, r: RegisterProjectResult, flags: Flags, verb: string): Promise<void>;
+/** "3 live, 1 backfilling, 1 failed (rpc_rate_limited)" — the one-line answer to "is my stuff ok?" */
+export declare function rollUp(projects: Array<{
+    status?: IndexStatus;
+    error?: {
+        class: string;
     };
-}
-/** Normalize a resolver base URL to its `/admin/projects` control-plane endpoint. */
-export declare function adminProjectsUrl(base: string): string;
-/** Register + index a project with a remote resolver (remote `abx add`/`index`). */
-export declare function remoteAddProject(base: string, token: string, body: RemoteAddBody): Promise<RemoteAddResult>;
-/** Stop a remote resolver from indexing a project (remote `abx forget`). */
-export declare function remoteRemoveProject(base: string, token: string, address: string): Promise<void>;
+}>): string;
 //# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,qHAAqH;IACrH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sGAAsG;IACtG,UAAU,CAAC,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACxF;yGACqG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC,CAAC;IAC7G;mGAC+F;IAC/F,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC;CAC9G;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAuBD,oFAAoF;AACpF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAQjH;AAED,4EAA4E;AAC5E,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrG"}
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"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"}