claimpaign 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Lichtstaub
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,88 @@
+# claimpaign
+
+Command line tool for Claimpaign sandbox campaigns and CIP-99 claims. It is made for events like hackathons, workshops and school classes where many people need preprod ada or test tokens quickly: the organizer creates a campaign from the terminal and hands out codes or QR cards, participants claim without owning a wallet yet, and the organization's own test tokens can be distributed the same way. It also claims CIP-99 codes from other faucets on the Cardano preprod testnet.
+
+## Install
+
+```
+npx claimpaign --help
+```
+
+Or install it globally:
+
+```
+npm install -g claimpaign
+```
+
+## Login
+
+Run `claimpaign login` and paste your sandbox API key when prompted. Get a key from Settings, Sandbox API on claimpaign.com, it looks like `cps_` followed by 40 characters. Setting `CLAIMPAIGN_TOKEN` skips `claimpaign login` entirely, every command reads it before anything else. `claimpaign login` itself always prompts for a key even when the variable is set, its whole purpose is storing a key in the config file.
+
+## Hackathon flow
+
+1. Deposit test tokens into the org wallet, or top up sandbox credits in the web interface. `claimpaign deposit` shows the wallet address and the top up link.
+2. `claimpaign campaign create --name "..." --claims 50 --ada 2` creates a campaign and exports its codes. Run one `campaign create` at a time, two parallel creations would produce two funded campaigns.
+3. `claimpaign campaign codes <id> --qr-dir ./qr --pdf codes.pdf` prints QR codes and a cut sheet PDF.
+4. Hand out the codes, on paper or as QR images.
+5. `claimpaign campaign status <id>` shows how many codes are claimed.
+6. `claimpaign campaign end <id>` ends the campaign and refunds unclaimed credits.
+
+## For participants
+
+```
+claimpaign claim <uri-or-code> <addr_test...>
+```
+
+Works with a scanned CIP-99 claim URI, or a bare code together with `--faucet <url>`. Also works against other CIP-99 faucets, not just Claimpaign campaigns.
+
+Sandbox (Cardano preprod) only, never mainnet.
+
+## Exit codes
+
+- `0` success
+- `1` the command ran but failed, an API error, a rejected claim, a network problem
+- `2` usage error, bad arguments or a missing required environment variable
+- `130` the login prompt was cancelled (Ctrl-C)
+
+## JSON output
+
+Every command accepts a top level `--json` flag, which prints the shape below instead of the human readable text. Fields marked `?` are only present when the value applies.
+
+- `login` no stdout output, only the exit code and the stored config change
+- `logout` no stdout output, only the exit code and the stored config change
+- `balance` `{ credits: <raw org credits body>, wallet: <raw org wallet body> }`
+- `deposit` `{ address, network }`
+- `campaign create` `{ campaign: { id, status, codePrefix, totalCodes }, pricing?, codesFile?, exportError? }`
+- `campaign list` `{ campaigns: [...] }`
+- `campaign status` the raw campaign GET body, `{ campaign, codes, queue, pagination }`
+- `campaign codes` without `--csv`/`--qr-dir`/`--pdf`, `{ campaign: { id, name, codePrefix }, codes: [{ code, status, claim_uri, fallback_url }] }`
+- `campaign codes` with `--csv`/`--qr-dir`/`--pdf`, `{ csv?, qrDir?, pdf?, count }`
+- `campaign end` the raw endpoint body, `{ ok, status, refunded? }`
+- `campaign pause` / `campaign resume` the raw endpoint body, `{ ok, status }`
+- `claim` the raw faucet response body, `{ code, status, message?, lovelaces?, tokens?, queue_position? }`, printed even when the claim is not accepted, before the command exits with an error
+
+## Configuration
+
+The CLI stores its login in `~/.config/claimpaign/config.json` (mode 0600).
+
+- `CLAIMPAIGN_API` API base URL, overrides the stored one and the default `https://claimpaign.com`
+- `CLAIMPAIGN_TOKEN` sandbox API key, overrides the stored one and skips the login prompt
+- `CLAIMPAIGN_CONFIG_DIR` directory for `config.json`, default `~/.config/claimpaign`
+
+## Development
+
+From a checkout: `npm install && npm run build`, then `node dist/bin.js --help`, or `npm link` once to get the `claimpaign` command. `npx claimpaign` only works with the published package.
+
+```
+npm test
+```
+
+`scripts/e2e.sh` runs an end to end test against a real API, not part of `npm test`. It needs `CLAIMPAIGN_API`, `CLAIMPAIGN_TOKEN` and `E2E_ADDRESSES` (a file with one `addr_test` address per line) as environment variables. The default run is a smoke test, `--full` adds a 60 claim acceptance run, `--foreign` adds a claim against an external CIP-99 faucet and needs `E2E_FOREIGN_URI` (a CIP-99 claim uri, for example the tUSDM preprod faucet).
+
+## Documentation
+
+https://claimpaign.com/docs
+
+## License
+
+Apache 2.0

package/dist/bin.js

@@ -0,0 +1,952 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command, CommanderError } from "commander";
+import { createRequire } from "module";
+
+// src/output.ts
+var UsageError = class extends Error {
+};
+var CancelledError = class extends Error {
+};
+function print(value, opts) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+    return;
+  }
+  if (typeof value === "string") process.stdout.write(value + "\n");
+  else process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+function formatAda(value) {
+  return value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+function table(rows) {
+  if (rows.length === 0) return "(none)";
+  const keys = Object.keys(rows[0]);
+  const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => String(r[k] ?? "").length)));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
+  return [line(keys), line(widths.map((w) => "-".repeat(w))), ...rows.map((r) => line(keys.map((k) => String(r[k] ?? ""))))].join("\n");
+}
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_API = "https://claimpaign.com";
+function configDir() {
+  return process.env.CLAIMPAIGN_CONFIG_DIR || join(homedir(), ".config", "claimpaign");
+}
+function configPath() {
+  return join(configDir(), "config.json");
+}
+function readConfig() {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+    return typeof parsed === "object" && parsed ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeConfig(patch, remove = []) {
+  const next = { ...readConfig(), ...patch };
+  for (const key of remove) delete next[key];
+  if (!existsSync(configDir())) mkdirSync(configDir(), { recursive: true, mode: 448 });
+  chmodSync(configDir(), 448);
+  writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n", { mode: 384 });
+  chmodSync(configPath(), 384);
+}
+function resolveToken() {
+  return process.env.CLAIMPAIGN_TOKEN || readConfig().token;
+}
+function resolveApi(flag) {
+  const raw = flag || process.env.CLAIMPAIGN_API || readConfig().api || DEFAULT_API;
+  return raw.replace(/\/+$/, "");
+}
+
+// src/api.ts
+var ApiError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var DEFAULT_RETRY_DELAYS_MS = [2e3, 4e3, 8e3];
+var DEFAULT_TIMEOUT_MS = 3e4;
+var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "PATCH"]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function messageFromBody(body, status) {
+  if (body && typeof body === "object") {
+    const record = body;
+    if (typeof record.error === "string") return record.error;
+    if (typeof record.message === "string") return record.message;
+    if (typeof record.status === "string") return record.status;
+  }
+  return `HTTP ${status}`;
+}
+async function apiRequest(options) {
+  const { api, token, method, path, body, headers, allow = [], retryDelaysMs = DEFAULT_RETRY_DELAYS_MS, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+  const url = `${api}${path}`;
+  const requestHeaders = { ...headers };
+  if (token) requestHeaders.authorization = `Bearer ${token}`;
+  if (body !== void 0) requestHeaders["content-type"] = "application/json";
+  const canRetry = RETRYABLE_METHODS.has(method.toUpperCase());
+  let attempt = 0;
+  for (; ; ) {
+    let status;
+    let parsedBody;
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      status = response.status;
+      const text = await response.text();
+      try {
+        parsedBody = text ? JSON.parse(text) : void 0;
+      } catch {
+        parsedBody = text;
+      }
+    } catch (err) {
+      const name = err?.name;
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new ApiError(0, `Timed out after ${timeoutMs / 1e3}s waiting for ${api}`);
+      }
+      throw new ApiError(0, `Could not reach ${api}`);
+    }
+    if (status === 429 && canRetry && attempt < retryDelaysMs.length) {
+      await sleep(retryDelaysMs[attempt]);
+      attempt += 1;
+      continue;
+    }
+    if (status >= 400 && !allow.includes(status)) {
+      throw new ApiError(status, messageFromBody(parsedBody, status), parsedBody);
+    }
+    return { status, body: parsedBody };
+  }
+}
+function requireToken() {
+  const token = resolveToken();
+  if (!token) throw new UsageError("Not logged in. Run: claimpaign login");
+  return token;
+}
+
+// src/commands/login.ts
+function promptSecret(question, input = process.stdin) {
+  process.stderr.write(question);
+  const isTty = !!input.isTTY && typeof input.setRawMode === "function";
+  if (isTty) input.setRawMode(true);
+  input.resume();
+  let buffer = "";
+  return new Promise((resolve, reject) => {
+    const finish = (value, err) => {
+      input.off("data", onData);
+      input.off("end", onEnd);
+      input.off("error", onError);
+      if (isTty) input.setRawMode(false);
+      input.pause();
+      input.unref?.();
+      if (isTty) process.stderr.write("\n");
+      if (err) reject(err);
+      else resolve((value ?? buffer).trim());
+    };
+    const onData = (chunk) => {
+      for (const ch of chunk.toString("utf8")) {
+        if (ch === "\r" || ch === "\n") return finish(buffer);
+        if (ch === "") {
+          finish(null, new CancelledError("Cancelled"));
+          return;
+        }
+        if (ch === "\x7F" || ch === "\b") buffer = buffer.slice(0, -1);
+        else buffer += ch;
+      }
+    };
+    const onEnd = () => finish(buffer);
+    const onError = (err) => finish(null, err);
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+  });
+}
+async function login(opts) {
+  const api = resolveApi(opts.api);
+  const token = opts.token ?? await promptSecret("Paste your sandbox API key (from Settings, Sandbox API): ");
+  if (!/^cps_[a-z2-9]{40}$/.test(token)) throw new UsageError("That does not look like a Claimpaign sandbox key (cps_ followed by 40 characters)");
+  try {
+    await apiRequest({ api, token, method: "GET", path: "/api/org/credits" });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) throw new Error("This key was not accepted. Create one under Settings, Sandbox API.");
+    throw err;
+  }
+  writeConfig({ token, api });
+  if (!opts.json) process.stdout.write(`Logged in. Key stored in ${configPathHint()} (sandbox only).
+`);
+}
+async function logout() {
+  writeConfig({}, ["token"]);
+}
+function configPathHint() {
+  return process.env.CLAIMPAIGN_CONFIG_DIR ? `${process.env.CLAIMPAIGN_CONFIG_DIR}/config.json` : "~/.config/claimpaign/config.json";
+}
+
+// src/commands/balance.ts
+async function balance(opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const [credits, wallet] = await Promise.all([
+    apiRequest({ api, token, method: "GET", path: "/api/org/credits" }),
+    apiRequest({ api, token, method: "GET", path: "/api/org/wallet" })
+  ]);
+  if (opts.json) {
+    print({ credits: credits.body, wallet: wallet.body }, { json: true });
+    return;
+  }
+  const creditsBody = credits.body;
+  const walletBody = wallet.body;
+  const ownTokens = walletBody.tokens.filter((t) => !t.platform);
+  const platformTokens = walletBody.tokens.filter((t) => t.platform);
+  const rows = [...ownTokens, ...platformTokens].map((t) => ({
+    // Asset names with a CIP-68 label or binary bytes must not break the table
+    Token: t.assetNameUtf8.replace(/[\x00-\x1f\x7f\ufffd]/g, "") + (t.platform ? " (platform)" : ""),
+    Available: t.available,
+    Reserved: t.reserved,
+    Settling: t.inFlight
+  }));
+  const lines = [
+    `Sandbox credits: ${formatAda(creditsBody.balance.ada)} tADA (locked in campaigns: ${formatAda(creditsBody.summary.lockedInCampaigns.ada)}, active campaigns: ${creditsBody.summary.activeCampaignCount})`,
+    `Org wallet: ${walletBody.address}  (${formatAda(walletBody.ada.ada)} tADA)`,
+    "",
+    table(rows)
+  ];
+  print(lines.join("\n"), { json: false });
+}
+
+// src/commands/deposit.ts
+async function deposit(opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const { body: wallet } = await apiRequest({ api, token, method: "GET", path: "/api/org/wallet" });
+  if (opts.json) {
+    print({ address: wallet.address, network: wallet.network }, { json: true });
+    return;
+  }
+  const lines = [
+    `Org wallet: ${wallet.address}`,
+    "",
+    "Send test tokens to this address. They stay the property of the organization and get distributed from there.",
+    "Any tADA sent along with them is used for payouts, it does not become sandbox credits.",
+    `Top up tADA credits in the web interface at ${api}/admin/create/.`,
+    "Preprod ada for the wallet itself comes from the Cardano testnet faucet: https://docs.cardano.org/cardano-testnets/tools/faucet"
+  ];
+  print(lines.join("\n"), { json: false });
+}
+
+// src/commands/campaign.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3, chmodSync as chmodSync2, rmSync } from "fs";
+import { join as join3 } from "path";
+import { randomInt, randomUUID, createHash } from "crypto";
+
+// src/codes.ts
+var CODE_LENGTH = 10;
+var CROCKFORD_CODE = /^[0-9A-HJKMNP-TV-Z]{10}$/;
+var LEGACY_HEX_CODE = /^[a-f0-9]{6,9}$/;
+function normalizeShortCode(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === CODE_LENGTH) {
+    const folded = trimmed.toUpperCase().replace(/O/g, "0").replace(/[IL]/g, "1");
+    return CROCKFORD_CODE.test(folded) ? folded : null;
+  }
+  const lower = trimmed.toLowerCase();
+  return LEGACY_HEX_CODE.test(lower) ? lower : null;
+}
+function splitFullCode(full) {
+  const sep = full.lastIndexOf("_");
+  if (sep < 0) return null;
+  const prefix = full.slice(0, sep);
+  const shortCode = full.slice(sep + 1);
+  if (!prefix || !shortCode) return null;
+  return { prefix, shortCode };
+}
+function buildClaimUri(api, prefix, shortCode) {
+  const faucetUrl = `${api}/api/claim/${prefix}`;
+  return `web+cardano://claim/v1?faucet_url=${encodeURIComponent(faucetUrl)}&code=${encodeURIComponent(shortCode)}`;
+}
+function buildFallbackUri(api, fullCode) {
+  return `${api}/api/qr/${fullCode}`;
+}
+var CLAIM_URI_PREFIXES = ["web+cardano://claim/v1", "web+cardano:claim/v1"];
+function parseClaimUri(uri) {
+  const qIndex = uri.indexOf("?");
+  if (qIndex < 0) return null;
+  const head = uri.slice(0, qIndex);
+  if (!CLAIM_URI_PREFIXES.includes(head)) return null;
+  const params = new URLSearchParams(uri.slice(qIndex + 1));
+  const faucetUrl = params.get("faucet_url");
+  const code = params.get("code");
+  if (!faucetUrl || !code) return null;
+  return { faucetUrl, code };
+}
+
+// src/export.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import QRCode from "qrcode";
+import { PDFDocument, StandardFonts } from "pdf-lib";
+var PAGE_WIDTH = 595;
+var PAGE_HEIGHT = 842;
+var COLS = 3;
+var ROWS = 4;
+var PER_PAGE = COLS * ROWS;
+var MARGIN = 36;
+var QR_SIZE = 120;
+function toWinAnsi(text) {
+  return Array.from(text).map((ch) => {
+    const code = ch.codePointAt(0) ?? 0;
+    return code >= 32 && code <= 126 || code >= 160 && code <= 255 ? ch : "?";
+  }).join("");
+}
+function csvField(value) {
+  if (/[",\n]/.test(value)) return '"' + value.replace(/"/g, '""') + '"';
+  return value;
+}
+function ensureDirFor(path) {
+  const dir = dirname(path);
+  if (dir) mkdirSync2(dir, { recursive: true });
+}
+function writeCsv(path, rows, columns) {
+  ensureDirFor(path);
+  const keys = columns ?? (rows.length > 0 ? Object.keys(rows[0]) : []);
+  if (keys.length === 0) {
+    writeFileSync2(path, "");
+    return;
+  }
+  const lines = [keys.map(csvField).join(",")];
+  for (const row of rows) lines.push(keys.map((k) => csvField(row[k] ?? "")).join(","));
+  writeFileSync2(path, lines.join("\n") + "\n");
+}
+async function writeQrImages(dir, items) {
+  mkdirSync2(dir, { recursive: true });
+  for (const item of items) {
+    await QRCode.toFile(join2(dir, `${item.code}.png`), item.uri, { width: 512, margin: 2 });
+  }
+}
+function drawCard(page, qrImage, code, title, monoFont, titleFont, cellX, cellTop, cellWidth) {
+  const qrX = cellX + (cellWidth - QR_SIZE) / 2;
+  const qrY = cellTop - QR_SIZE - 12;
+  page.drawImage(qrImage, { x: qrX, y: qrY, width: QR_SIZE, height: QR_SIZE });
+  const safeCode = toWinAnsi(code);
+  const codeSize = 10;
+  const codeWidth = monoFont.widthOfTextAtSize(safeCode, codeSize);
+  page.drawText(safeCode, { x: cellX + (cellWidth - codeWidth) / 2, y: qrY - 14, size: codeSize, font: monoFont });
+  const safeTitle = toWinAnsi(title);
+  const titleSize = 7;
+  const titleWidth = titleFont.widthOfTextAtSize(safeTitle, titleSize);
+  page.drawText(safeTitle, { x: cellX + (cellWidth - titleWidth) / 2, y: qrY - 26, size: titleSize, font: titleFont });
+}
+async function writePdf(path, items, title) {
+  ensureDirFor(path);
+  const doc = await PDFDocument.create();
+  const monoFont = await doc.embedFont(StandardFonts.Courier);
+  const titleFont = await doc.embedFont(StandardFonts.Helvetica);
+  const cellWidth = (PAGE_WIDTH - 2 * MARGIN) / COLS;
+  const cellHeight = (PAGE_HEIGHT - 2 * MARGIN) / ROWS;
+  let page;
+  let onPage = 0;
+  for (const item of items) {
+    if (!page || onPage === PER_PAGE) {
+      page = doc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
+      onPage = 0;
+    }
+    const col = onPage % COLS;
+    const row = Math.floor(onPage / COLS);
+    const cellX = MARGIN + col * cellWidth;
+    const cellTop = PAGE_HEIGHT - MARGIN - row * cellHeight;
+    const qrBuffer = await QRCode.toBuffer(item.uri, { width: 256, margin: 1 });
+    const qrImage = await doc.embedPng(qrBuffer);
+    drawCard(page, qrImage, item.code, title, monoFont, titleFont, cellX, cellTop, cellWidth);
+    onPage += 1;
+  }
+  const bytes = await doc.save();
+  writeFileSync2(path, bytes);
+}
+
+// src/commands/campaign-codes.ts
+var MAX_PAGES = 1e3;
+var CSV_COLUMNS = ["code", "status", "claim_uri", "fallback_url"];
+async function loadAllCodes(params) {
+  const { api, token, campaignId } = params;
+  const first = params.firstPage ?? (await apiRequest({
+    api,
+    token,
+    method: "GET",
+    path: `/api/admin/campaign/${campaignId}?page=1&limit=200`
+  })).body;
+  const dedup = /* @__PURE__ */ new Map();
+  for (const c of first.codes) dedup.set(c.code, c);
+  const totalPages = Number.isFinite(first.pagination.pages) ? Math.min(first.pagination.pages, MAX_PAGES) : 1;
+  for (let p = 2; p <= totalPages; p++) {
+    const res = await apiRequest({
+      api,
+      token,
+      method: "GET",
+      path: `/api/admin/campaign/${campaignId}?page=${p}&limit=200`
+    });
+    for (const c of res.body.codes) dedup.set(c.code, c);
+  }
+  return { campaign: first.campaign, codes: [...dedup.values()] };
+}
+function buildExportItems(rows, fallback) {
+  return rows.map((r) => ({ code: r.code, uri: fallback ? r.fallback_url : r.claim_uri }));
+}
+async function campaignCodes(id, opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const { campaign, codes } = await loadAllCodes({ api, token, campaignId: id });
+  const isShared = campaign.code_mode === "shared";
+  const filtered = opts.all || isShared ? codes : codes.filter((c) => c.status === "unclaimed");
+  const items = filtered.map((c) => {
+    const split = splitFullCode(c.code);
+    const shortCode = split?.shortCode ?? c.code;
+    const codePrefix = split?.prefix ?? campaign.code_prefix;
+    return {
+      code: c.code,
+      status: c.status,
+      claim_uri: buildClaimUri(api, codePrefix, shortCode),
+      fallback_url: buildFallbackUri(api, c.code)
+    };
+  });
+  const hasOutputs = Boolean(opts.csv || opts.qrDir || opts.pdf);
+  if (!hasOutputs) {
+    if (opts.json) {
+      print({ campaign: { id: campaign.id, name: campaign.name, codePrefix: campaign.code_prefix }, codes: items }, { json: true });
+    } else {
+      print(table(items.map((it) => ({ code: it.code, status: it.status, claim_uri: it.claim_uri }))), { json: false });
+    }
+    return;
+  }
+  const exportItems = buildExportItems(items, Boolean(opts.fallback));
+  const result = { count: items.length };
+  if (opts.csv) {
+    writeCsv(opts.csv, items.map((it) => ({ code: it.code, status: it.status, claim_uri: it.claim_uri, fallback_url: it.fallback_url })), CSV_COLUMNS);
+    result.csv = opts.csv;
+  }
+  if (opts.qrDir) {
+    await writeQrImages(opts.qrDir, exportItems);
+    result.qrDir = opts.qrDir;
+  }
+  if (opts.pdf) {
+    await writePdf(opts.pdf, exportItems, campaign.name);
+    result.pdf = opts.pdf;
+  }
+  if (opts.json) {
+    print(result, { json: true });
+    return;
+  }
+  const lines = [];
+  if (result.csv) lines.push(`Wrote ${items.length} codes to ${result.csv}`);
+  if (result.qrDir) lines.push(`Wrote ${items.length} QR images to ${result.qrDir}`);
+  if (result.pdf) lines.push(`Wrote ${items.length} codes to ${result.pdf}`);
+  print(lines.join("\n"), { json: false });
+}
+
+// src/commands/campaign.ts
+var PREFIX_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+var TOKEN_ARG = /^([a-fA-F0-9]{56})\.([a-fA-F0-9]*):([0-9]+)$/;
+var DEFAULT_POLL_MS = 1e4;
+var DEFAULT_POLL_TIMEOUT_MS = 9e5;
+var DEFAULT_END_WAIT_MS = 2e4;
+var DEFAULT_END_WAIT_TIMEOUT_MS = 9e5;
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+function pendingPath() {
+  return join3(configDir(), "pending-create.json");
+}
+function readPendingEntry() {
+  try {
+    const parsed = JSON.parse(readFileSync2(pendingPath(), "utf8"));
+    if (parsed && typeof parsed === "object" && typeof parsed.key === "string" && typeof parsed.api === "string" && typeof parsed.tokenHash === "string" && parsed.body && typeof parsed.body === "object" && parsed.body.network === "preprod") {
+      return parsed;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function writePendingEntry(entry) {
+  if (!existsSync2(configDir())) mkdirSync3(configDir(), { recursive: true, mode: 448 });
+  chmodSync2(configDir(), 448);
+  writeFileSync3(pendingPath(), JSON.stringify(entry, null, 2) + "\n", { mode: 384 });
+  chmodSync2(pendingPath(), 384);
+}
+function deletePendingEntry() {
+  try {
+    rmSync(pendingPath());
+  } catch {
+  }
+}
+function derivePrefix(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9]/g, "").toUpperCase().slice(0, 8);
+  const base = cleaned || "CP";
+  let suffix = "";
+  for (let i = 0; i < 2; i++) suffix += PREFIX_CHARS[randomInt(PREFIX_CHARS.length)];
+  return base + suffix;
+}
+function parseTokenArg(raw) {
+  const match = TOKEN_ARG.exec(raw);
+  if (!match) {
+    throw new UsageError(`Invalid --token value "${raw}", expected <policyId 56 hex>.<assetNameHex>:<quantity digits>`);
+  }
+  const [, policyId, assetNameHex, quantity] = match;
+  return { unit: `${policyId}.${assetNameHex}`.toLowerCase(), quantity };
+}
+function buildRequestBody(opts, name, claims, prefix) {
+  const body = {
+    name,
+    codePrefix: prefix,
+    codeCount: claims,
+    network: "preprod"
+  };
+  if (opts.ada !== void 0) body.adaPerClaim = Math.round(opts.ada * 1e6);
+  if (opts.token && opts.token.length > 0) body.tokenBundle = opts.token.map(parseTokenArg);
+  if (opts.shared) body.codeMode = "shared";
+  if (opts.expires) body.expiresAt = opts.expires;
+  if (opts.description) body.description = opts.description;
+  return body;
+}
+function isDefinitiveRejection(status, body) {
+  if (status === 400 || status === 401 || status === 403 || status === 404 || status === 422) return true;
+  if (status === 409) {
+    const record = body;
+    if (record?.campaign?.status === "creation_failed") return true;
+    if (typeof record?.error === "string" && record.error.includes("creation_failed")) return true;
+  }
+  return false;
+}
+function formatLovelace(lovelace) {
+  return (lovelace / 1e6).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+function pendingMismatchMessage(pending, api, tokenHash) {
+  const reasons = [];
+  if (pending.api !== api) reasons.push(`the pending attempt targets ${pending.api}, this run targets ${api}`);
+  if (pending.tokenHash !== tokenHash) reasons.push("the pending attempt used a different API key");
+  return `A pending campaign creation exists, but ${reasons.join(" and ")}. Run with --fresh to start a new one.`;
+}
+async function pollUntilActive(params) {
+  const { api, token, campaignId, pollMs, deadline } = params;
+  for (; ; ) {
+    const res = await apiRequest({
+      api,
+      token,
+      method: "GET",
+      path: `/api/admin/campaign/${campaignId}?page=1&limit=200`
+    });
+    const page1 = res.body;
+    if (page1.campaign.status === "active") return page1;
+    if (page1.campaign.status === "creation_failed") {
+      deletePendingEntry();
+      throw new Error(`Campaign ${campaignId} failed during creation. Check the dashboard or start a new campaign with --fresh.`);
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Campaign ${campaignId} is still settling. It stays pending, run "claimpaign campaign create" again to resume it, or use --fresh to start a new campaign instead.`
+      );
+    }
+    await sleep(pollMs);
+  }
+}
+async function exportCodes(params) {
+  const { api, token, campaignId, page1, outDir } = params;
+  const { campaign, codes } = await loadAllCodes({ api, token, campaignId, firstPage: page1 });
+  const prefix = campaign.code_prefix;
+  const rows = codes.map((c) => {
+    const split = splitFullCode(c.code);
+    const shortCode = split?.shortCode ?? c.code;
+    const codePrefix = split?.prefix ?? prefix;
+    return { code: c.code, status: "unclaimed", claim_uri: buildClaimUri(api, codePrefix, shortCode), fallback_url: buildFallbackUri(api, c.code) };
+  });
+  mkdirSync3(outDir, { recursive: true });
+  const csvPath = join3(outDir, `${prefix}-codes.csv`);
+  writeCsv(csvPath, rows, CSV_COLUMNS);
+  return csvPath;
+}
+async function campaignCreate(opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const tokenHash = hashToken(token);
+  const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  const pollTimeoutMs = opts.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  let pending = readPendingEntry();
+  if (opts.fresh && pending) {
+    deletePendingEntry();
+    pending = void 0;
+  }
+  let key;
+  let body;
+  if (pending) {
+    if (pending.api !== api || pending.tokenHash !== tokenHash) {
+      throw new UsageError(pendingMismatchMessage(pending, api, tokenHash));
+    }
+    key = pending.key;
+    body = pending.body;
+    const ageHours = Math.floor((Date.now() - new Date(pending.createdAt).getTime()) / 36e5);
+    process.stderr.write(`Resuming the previous creation from ${pending.createdAt} (key ${pending.key.slice(0, 8)}...)
+`);
+    if (ageHours >= 24) process.stderr.write(`This attempt is ${ageHours} hours old.
+`);
+  } else {
+    const { name, claims } = opts;
+    if (!name || claims === void 0) throw new UsageError("--name and --claims are required to create a new campaign");
+    if (!Number.isInteger(claims) || claims <= 0) throw new UsageError("--claims must be a positive integer");
+    if (opts.ada !== void 0 && (!Number.isFinite(opts.ada) || opts.ada < 0)) throw new UsageError("--ada must be a non negative number");
+    const prefix = opts.prefix || derivePrefix(name);
+    body = buildRequestBody(opts, name, claims, prefix);
+    key = randomUUID();
+    writePendingEntry({ key, api, tokenHash, body, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  let createBody;
+  try {
+    const res = await apiRequest({
+      api,
+      token,
+      method: "POST",
+      path: "/api/admin/campaign/create",
+      body,
+      headers: { "Idempotency-Key": key }
+    });
+    createBody = res.body;
+  } catch (err) {
+    if (err instanceof ApiError && isDefinitiveRejection(err.status, err.body)) deletePendingEntry();
+    throw err;
+  }
+  const campaignId = createBody.campaign.id;
+  const pricing = createBody.pricing;
+  if (createBody.campaign.status === "creating") process.stderr.write("Funding is settling.\n");
+  const page1 = await pollUntilActive({ api, token, campaignId, pollMs, deadline: Date.now() + pollTimeoutMs });
+  deletePendingEntry();
+  let codesFile;
+  let exportError;
+  try {
+    codesFile = await exportCodes({ api, token, campaignId, page1, outDir: opts.out || process.cwd() });
+  } catch (err) {
+    exportError = `Could not export codes for campaign ${campaignId}: ${err.message}. Run: claimpaign campaign codes ${campaignId}`;
+  }
+  const result = {
+    campaign: {
+      id: campaignId,
+      status: page1.campaign.status,
+      codePrefix: page1.campaign.code_prefix,
+      totalCodes: page1.campaign.total_codes
+    },
+    ...pricing ? { pricing } : {},
+    ...codesFile ? { codesFile } : {},
+    ...exportError ? { exportError } : {}
+  };
+  if (opts.json) {
+    print(result, { json: true });
+  } else {
+    const lines = [`Campaign ${result.campaign.id} is active.`, `Prefix: ${result.campaign.codePrefix}`];
+    if (page1.campaign.code_mode === "shared") lines.push(`Claim capacity: ${result.campaign.totalCodes} (one shared code)`);
+    else lines.push(`Codes: ${result.campaign.totalCodes}`);
+    lines.push(`Cost: ${pricing ? `${formatLovelace(pricing.totalCost)} tADA` : "see claimpaign campaign status"}`);
+    if (codesFile) {
+      lines.push(`Codes exported to ${codesFile}`);
+      if (page1.campaign.code_mode === "shared") lines.push("Anyone with this code can claim it once per wallet.");
+    } else if (exportError) {
+      lines.push("Codes could not be exported, see the error below.");
+    }
+    print(lines.join("\n"), { json: false });
+  }
+  if (result.exportError) throw new Error(result.exportError);
+  return result;
+}
+async function campaignList(opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const campaigns = [];
+  let page = 1;
+  for (; ; ) {
+    const { body } = await apiRequest({
+      api,
+      token,
+      method: "GET",
+      path: `/api/admin/campaigns?limit=100&page=${page}`
+    });
+    campaigns.push(...body.campaigns);
+    if (!Number.isFinite(body.pages) || page >= body.pages || page >= MAX_PAGES) break;
+    page += 1;
+  }
+  if (opts.json) {
+    print({ campaigns }, { json: true });
+    return;
+  }
+  const rows = campaigns.map((c) => ({
+    id: c.id,
+    name: c.name,
+    status: c.status,
+    "claimed/capacity": `${c.codes_claimed}/${c.total_codes}`,
+    prefix: c.code_prefix,
+    created: c.created_at
+  }));
+  print(table(rows), { json: false });
+}
+async function campaignStatus(id, opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const { body } = await apiRequest({
+    api,
+    token,
+    method: "GET",
+    path: `/api/admin/campaign/${id}?page=1&limit=200`
+  });
+  if (opts.json) {
+    print(body, { json: true });
+    return;
+  }
+  const c = body.campaign;
+  const lines = [
+    `Campaign: ${c.id}`,
+    `Name: ${c.name}`,
+    `Status: ${c.status}`,
+    `Prefix: ${c.code_prefix}`,
+    `Mode: ${c.code_mode}`,
+    `Progress: ${c.codes_claimed}/${c.total_codes}`,
+    `Queue pending: ${body.queue.pending}`,
+    `Created: ${c.created_at}`
+  ];
+  print(lines.join("\n"), { json: false });
+}
+function errorText(body) {
+  if (body && typeof body === "object" && typeof body.error === "string") {
+    return body.error;
+  }
+  return "";
+}
+async function campaignEnd(id, opts) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const waitMs = opts.waitMs ?? DEFAULT_END_WAIT_MS;
+  const waitTimeoutMs = opts.waitTimeoutMs ?? DEFAULT_END_WAIT_TIMEOUT_MS;
+  const deadline = Date.now() + waitTimeoutMs;
+  for (; ; ) {
+    const res = await apiRequest({
+      api,
+      token,
+      method: "PATCH",
+      path: `/api/admin/campaign/${id}`,
+      body: { status: "ended" },
+      allow: [409]
+    });
+    if (res.status === 200) {
+      if (opts.json) print(res.body, { json: true });
+      else print(`Campaign ${id} ended, refunded ${formatLovelace(res.body.refunded ?? 0)} tADA`, { json: false });
+      return;
+    }
+    const message = errorText(res.body);
+    if (!message.includes("closing")) throw new ApiError(409, message || "HTTP 409", res.body);
+    if (!opts.wait) throw new Error("Payouts are still settling, run again with --wait");
+    if (Date.now() >= deadline) {
+      throw new Error(`Campaign ${id} payouts are still settling after ${Math.round(waitTimeoutMs / 6e4)} minutes. Run again to keep waiting.`);
+    }
+    process.stderr.write("Payouts are still settling, retrying...\n");
+    await sleep(waitMs);
+  }
+}
+async function setCampaignStatus(id, status, opts, verb) {
+  const token = requireToken();
+  const api = resolveApi(opts.api);
+  const { body } = await apiRequest({
+    api,
+    token,
+    method: "PATCH",
+    path: `/api/admin/campaign/${id}`,
+    body: { status }
+  });
+  if (opts.json) print(body, { json: true });
+  else print(`Campaign ${id} ${verb}`, { json: false });
+}
+async function campaignPause(id, opts) {
+  await setCampaignStatus(id, "paused", opts, "paused");
+}
+async function campaignResume(id, opts) {
+  await setCampaignStatus(id, "active", opts, "resumed");
+}
+
+// src/commands/claim.ts
+var STATUS_MESSAGES = {
+  notfound: "Unknown code",
+  alreadyclaimed: "This code was already claimed",
+  expired: "This campaign has expired",
+  ratelimited: "Too many attempts from this network, wait 15 minutes",
+  soldout: "All claims of this campaign are used up",
+  walletlimitreached: "This wallet reached the claim limit",
+  nostakekey: "Use a base address with a staking part",
+  invalidaddress: "The address was not accepted",
+  notclaimable: "This campaign is not accepting claims right now",
+  maintenance: "The faucet is in maintenance",
+  invalidrequest: "The faucet rejected the request",
+  missingcode: "The faucet rejected the request",
+  error: "The faucet reported an error"
+};
+function resolveClaimTarget(input, faucetOpt, api) {
+  if (input.startsWith("web+cardano:")) {
+    const parsed = parseClaimUri(input);
+    if (!parsed) throw new UsageError("Not a valid CIP-99 claim URI");
+    return parsed;
+  }
+  if (faucetOpt) {
+    return { faucetUrl: faucetOpt, code: input };
+  }
+  const split = splitFullCode(input);
+  if (!split) throw new UsageError("This does not look like a Claimpaign code (expected PREFIX_code)");
+  const shortCode = normalizeShortCode(split.shortCode);
+  if (!shortCode) throw new UsageError("This does not look like a Claimpaign code");
+  return { faucetUrl: `${api}/api/claim/${split.prefix.toUpperCase()}`, code: shortCode };
+}
+function formatAccepted(body) {
+  const ada = Number(body.lovelaces ?? 0) / 1e6;
+  const parts = [`Accepted: ${formatAda(ada)} tADA`];
+  if (body.tokens && Object.keys(body.tokens).length > 0) {
+    const tokenList = Object.entries(body.tokens).map(([unit, qty]) => `${unit}:${qty}`).join(", ");
+    parts.push(`tokens ${tokenList}`);
+  }
+  if (typeof body.queue_position === "number") {
+    parts.push(`queue position ${body.queue_position}`);
+  }
+  return parts.join(", ");
+}
+async function claim(input, address, opts) {
+  const api = resolveApi(opts.api);
+  const { faucetUrl, code } = resolveClaimTarget(input, opts.faucet, api);
+  if (!address.startsWith("addr_test")) {
+    throw new UsageError("This tool claims on the Cardano preprod testnet only, mainnet addresses (addr1...) are not accepted.");
+  }
+  const url = new URL(faucetUrl);
+  const { status, body: rawBody } = await apiRequest({
+    api: url.origin,
+    method: "POST",
+    path: url.pathname + url.search,
+    body: { code, address },
+    allow: [400, 401, 403, 404, 409, 410, 422, 429, 500, 503]
+  });
+  if (!rawBody || typeof rawBody !== "object") {
+    throw new Error(`The faucet answered with an unexpected response (HTTP ${status})`);
+  }
+  const body = rawBody;
+  if (body.status === "accepted") {
+    if (opts.json) {
+      print(body, { json: true });
+      return;
+    }
+    print(formatAccepted(body), { json: false });
+    return;
+  }
+  if (opts.json) print(body, { json: true });
+  const base = STATUS_MESSAGES[body.status] ?? `The faucet answered with status ${body.status}`;
+  throw new Error(body.message ? `${base} (${body.message})` : base);
+}
+
+// src/cli.ts
+var { version } = createRequire(import.meta.url)("../package.json");
+function buildProgram() {
+  const program = new Command("claimpaign").description("Claimpaign sandbox campaigns and CIP-99 claims from the terminal").version(version).option("--api <url>", "API base URL (default https://claimpaign.com, or CLAIMPAIGN_API)").option("--json", "machine readable output", false).exitOverride();
+  program.command("login").description("Store a sandbox API key").action(async () => {
+    const opts = program.opts();
+    await login({ api: opts.api, json: opts.json });
+  });
+  program.command("logout").description("Remove the stored sandbox API key").action(async () => {
+    await logout();
+    if (!program.opts().json) process.stdout.write("Logged out.\n");
+  });
+  program.command("balance").description("Show the sandbox credit balance").action(async () => {
+    const opts = program.opts();
+    await balance({ api: opts.api, json: opts.json });
+  });
+  program.command("deposit").description("Show the organization wallet address and how to add credits").action(async () => {
+    const opts = program.opts();
+    await deposit({ api: opts.api, json: opts.json });
+  });
+  const campaign = program.command("campaign").description("Manage sandbox campaigns");
+  campaign.command("create").description("Create a sandbox campaign and export its codes").option("--name <text>", "campaign name, required to start a new campaign, not needed to resume a pending one").option("--claims <n>", "number of claim codes, required to start a new campaign, not needed to resume a pending one").option("--ada <tADA>", "ada per claim, in tADA").option("--token <policy.assethex:qty>", "token bundle item, repeatable", (value, previous) => [...previous, value], []).option("--shared", "one shared code for every claim", false).option("--prefix <PREFIX>", "claim code prefix, derived from the name when omitted").option("--expires <ISO>", "expiry timestamp").option("--description <text>", "campaign description").option("--out <dir>", "directory for the exported codes CSV (default the current directory)").option("--fresh", "discard a pending creation attempt and start a new one", false).action(async (cmdOpts) => {
+    const opts = program.opts();
+    await campaignCreate({
+      api: opts.api,
+      json: opts.json,
+      name: cmdOpts.name,
+      claims: cmdOpts.claims !== void 0 ? Number(cmdOpts.claims) : void 0,
+      ada: cmdOpts.ada !== void 0 ? Number(cmdOpts.ada) : void 0,
+      token: cmdOpts.token,
+      shared: cmdOpts.shared,
+      prefix: cmdOpts.prefix,
+      expires: cmdOpts.expires,
+      description: cmdOpts.description,
+      out: cmdOpts.out,
+      fresh: cmdOpts.fresh
+    });
+  });
+  campaign.command("list").description("List sandbox campaigns").action(async () => {
+    const opts = program.opts();
+    await campaignList({ api: opts.api, json: opts.json });
+  });
+  campaign.command("status <id>").description("Show a sandbox campaign's status, progress and claim queue").action(async (id) => {
+    const opts = program.opts();
+    await campaignStatus(id, { api: opts.api, json: opts.json });
+  });
+  campaign.command("codes <id>").description("Export a campaign's codes as CSV, QR images and/or a print-ready PDF").option("--csv <file>", "write a CSV file").option("--qr-dir <dir>", "write one QR PNG per code into this directory").option("--pdf <file>", "write a print-ready PDF with one card per code").option("--fallback", "use the HTTPS fallback URL instead of the wallet deep link for QR and PDF", false).option("--all", "include already claimed codes", false).action(async (id, cmdOpts) => {
+    const opts = program.opts();
+    await campaignCodes(id, {
+      api: opts.api,
+      json: opts.json,
+      csv: cmdOpts.csv,
+      qrDir: cmdOpts.qrDir,
+      pdf: cmdOpts.pdf,
+      fallback: cmdOpts.fallback,
+      all: cmdOpts.all
+    });
+  });
+  campaign.command("end <id>").description("End a sandbox campaign and refund unclaimed credits").option("--wait", "keep retrying while payouts are settling", false).action(async (id, cmdOpts) => {
+    const opts = program.opts();
+    await campaignEnd(id, { api: opts.api, json: opts.json, wait: cmdOpts.wait });
+  });
+  campaign.command("pause <id>").description("Pause a sandbox campaign").action(async (id) => {
+    const opts = program.opts();
+    await campaignPause(id, { api: opts.api, json: opts.json });
+  });
+  campaign.command("resume <id>").description("Resume a paused sandbox campaign").action(async (id) => {
+    const opts = program.opts();
+    await campaignResume(id, { api: opts.api, json: opts.json });
+  });
+  program.command("claim <uri-or-code> <address>").description("Claim a CIP-99 code on the Cardano preprod testnet").option("--faucet <url>", "post a bare code to this faucet url instead of deriving one from --api").action(async (input, address, cmdOpts) => {
+    const opts = program.opts();
+    await claim(input, address, { api: opts.api, json: opts.json, faucet: cmdOpts.faucet });
+  });
+  return program;
+}
+async function run(argv) {
+  try {
+    await buildProgram().parseAsync(argv);
+    return 0;
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help") return 0;
+      return 2;
+    }
+    if (err instanceof CancelledError) {
+      process.stderr.write("Cancelled\n");
+      return 130;
+    }
+    process.stderr.write(`Error: ${err?.message ?? String(err)}
+`);
+    return err instanceof UsageError ? 2 : 1;
+  }
+}
+
+// src/bin.ts
+process.exitCode = await run(process.argv);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "claimpaign",
+  "version": "0.1.0",
+  "description": "Command line tool for Claimpaign sandbox campaigns and CIP-99 claims",
+  "type": "module",
+  "bin": {
+    "claimpaign": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/bin.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lichtstaub/claimpaign-cli.git"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "pdf-lib": "^1.17.1",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "@types/qrcode": "^1.5.6",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  }
+}