@supercycle/cli 0.1.0

package/dist/components/Status.js

@@ -0,0 +1,33 @@
+import { Text } from "ink";
+import React from "react";
+import { titleCase } from "../lib/format.js";
+// Map any status enum value to a sensible color.
+function colorFor(status) {
+    switch (status) {
+        case "complete":
+        case "fulfilled":
+        case "received":
+        case "packed":
+            return "green";
+        case "overdue":
+            return "red";
+        case "in_progress":
+        case "printed":
+            return "yellow";
+        case "scheduled":
+        case "due":
+        case "unfulfilled":
+        case "unreceived":
+            return "cyan";
+        case "cancelled":
+        case "pending":
+            return "gray";
+        default:
+            return "white";
+    }
+}
+export default function Status({ value }) {
+    if (!value)
+        return (React.createElement(Text, { dimColor: true, wrap: "truncate" }, "\u2014"));
+    return (React.createElement(Text, { color: colorFor(value), wrap: "truncate" }, titleCase(value)));
+}

package/dist/hooks/useAsync.js

@@ -0,0 +1,32 @@
+// This is a generic hook that forwards a caller-supplied `deps` array to
+// useEffect, so the dependencies can't be a static literal here.
+/* oxlint-disable react-hooks/exhaustive-deps */
+import { useEffect, useState } from "react";
+// Run an async function once on mount (and when deps change), tracking
+// loading/data/error state. Ignores results after unmount.
+export function useAsync(fn, deps) {
+    const [state, setState] = useState({ loading: true });
+    useEffect(() => {
+        let cancelled = false;
+        setState({ loading: true });
+        void (async () => {
+            try {
+                const data = await fn();
+                if (!cancelled)
+                    setState({ loading: false, data });
+            }
+            catch (error) {
+                if (!cancelled) {
+                    setState({
+                        loading: false,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                    });
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, deps);
+    return state;
+}

package/dist/lib/client.js

@@ -0,0 +1,302 @@
+export const DEFAULT_BASE_URL = "https://app.supercycle.com/api/v1";
+export class ApiError extends Error {
+    status;
+    body;
+    retryAfter;
+    constructor(message, options) {
+        super(message);
+        this.name = "ApiError";
+        this.status = options.status;
+        this.body = options.body;
+        this.retryAfter = options.retryAfter;
+    }
+}
+function isDateRange(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Serialize filters into query params. Date-range objects use bracket
+// notation (e.g. `rentalStart[gte]=2024-01-01`), as the API expects.
+function buildQuery(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "") {
+            continue;
+        }
+        if (isDateRange(value)) {
+            for (const op of ["gt", "lt", "gte", "lte"]) {
+                const opValue = value[op];
+                if (opValue !== undefined && opValue !== "") {
+                    search.append(`${key}[${op}]`, opValue);
+                }
+            }
+            continue;
+        }
+        search.append(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+export class SupercycleClient {
+    token;
+    baseUrl;
+    constructor(options) {
+        this.token = options.token;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    }
+    async request(path, options = {}) {
+        const { method = "GET", query = {}, body } = options;
+        const url = `${this.baseUrl}${path}${buildQuery(query)}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            throw new ApiError(`Could not reach the Supercycle API: ${error instanceof Error ? error.message : String(error)}`, { status: 0 });
+        }
+        if (!response.ok) {
+            throw await this.toApiError(response);
+        }
+        // 204 No Content and other empty bodies have nothing to parse.
+        if (response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+    async toApiError(response) {
+        const body = await response.text().catch(() => "");
+        switch (response.status) {
+            case 401:
+            case 403:
+                return new ApiError("Invalid or missing API key. Run `supercycle login` to set one.", {
+                    status: response.status,
+                    body,
+                });
+            case 404:
+                return new ApiError("Not found.", {
+                    status: response.status,
+                    body,
+                });
+            case 429: {
+                const retryAfter = response.headers.get("Retry-After") ?? undefined;
+                return new ApiError(`Rate limited by the Supercycle API${retryAfter ? ` — retry after ${retryAfter}s` : ""}.`, { status: response.status, body, retryAfter });
+            }
+            default:
+                return new ApiError(`Supercycle API request failed (${response.status}).${body ? ` ${body}` : ""}`, { status: response.status, body });
+        }
+    }
+    // GET /rentals — list cycles with optional filters.
+    listCycles(filters = {}) {
+        return this.request("/rentals", { query: { ...filters } });
+    }
+    // Follow keyset pagination to gather every matching cycle. Caps the number
+    // of pages as a safety net against an unexpected server response.
+    async listAllCycles(filters = {}, maxPages = 1000) {
+        const all = [];
+        let page = filters.page;
+        for (let i = 0; i < maxPages; i++) {
+            // Sequential by design: each request needs the previous page's cursor.
+            // oxlint-disable-next-line no-await-in-loop
+            const res = await this.listCycles({ ...filters, page });
+            all.push(...res.data);
+            if (!res.nextPage) {
+                return { data: all, nextPage: null };
+            }
+            page = res.nextPage;
+        }
+        return { data: all, nextPage: null };
+    }
+    // GET /rentals/{id} — retrieve a single cycle.
+    getCycle(id, options = {}) {
+        return this.request(`/rentals/${id}`, {
+            query: { include: options.include },
+        });
+    }
+    // PUT /rentals/{id} — update a cycle.
+    updateCycle(id, body) {
+        return this.request(`/rentals/${id}`, { method: "PUT", body });
+    }
+    // GET /items — list inventory items with optional filters.
+    listItems(filters = {}) {
+        return this.request("/items", { query: { ...filters } });
+    }
+    // Follow keyset pagination to gather every matching item. Caps the number of
+    // pages as a safety net against an unexpected server response.
+    async listAllItems(filters = {}, maxPages = 1000) {
+        const all = [];
+        let page = filters.page;
+        for (let i = 0; i < maxPages; i++) {
+            // Sequential by design: each request needs the previous page's cursor.
+            // oxlint-disable-next-line no-await-in-loop
+            const res = await this.listItems({ ...filters, page });
+            all.push(...res.data);
+            if (!res.nextPage) {
+                return { data: all, nextPage: null };
+            }
+            page = res.nextPage;
+        }
+        return { data: all, nextPage: null };
+    }
+    // POST /items — create one or more items against an imported product.
+    // The live API returns a bare array of items (despite the docs showing an
+    // `{ items }` wrapper); handle both shapes defensively.
+    async createItems(body) {
+        const res = await this.request("/items", {
+            method: "POST",
+            body,
+        });
+        if (Array.isArray(res))
+            return res;
+        return Array.isArray(res.items) ? res.items : [res.items];
+    }
+    // PUT /items/{id} — update an item's serial, condition, status, etc.
+    updateItem(id, body) {
+        return this.request(`/items/${id}`, { method: "PUT", body });
+    }
+    // GET /items/{id} — retrieve a single item.
+    getItem(id, options = {}) {
+        return this.request(`/items/${id}`, {
+            query: { include: options.include },
+        });
+    }
+    // GET /products — list products with optional search.
+    listProducts(filters = {}) {
+        return this.request("/products", { query: { ...filters } });
+    }
+    // Follow keyset pagination to gather every matching product. Caps the number
+    // of pages as a safety net against an unexpected server response.
+    async listAllProducts(filters = {}, maxPages = 1000) {
+        const all = [];
+        let page = filters.page;
+        for (let i = 0; i < maxPages; i++) {
+            // Sequential by design: each request needs the previous page's cursor.
+            // oxlint-disable-next-line no-await-in-loop
+            const res = await this.listProducts({ ...filters, page });
+            all.push(...res.data);
+            if (!res.nextPage) {
+                return { data: all, nextPage: null };
+            }
+            page = res.nextPage;
+        }
+        return { data: all, nextPage: null };
+    }
+    // GET /availability_timelines — per-day availability for a variant.
+    // Maps the camelCase input to the snake_case query params the API expects.
+    getVariantAvailability(opts) {
+        return this.request("/availability_timelines", {
+            query: {
+                variant_shopify_id: opts.variantShopifyId,
+                location_id: opts.locationId,
+                delivery_method_type: opts.deliveryMethodType,
+            },
+        });
+    }
+    // POST /products — import Shopify products into Supercycle by ID.
+    // The live endpoint returns snake_case `product_ids`; send both casings in
+    // the body and normalize the response to camelCase.
+    async importProducts(productIds) {
+        const res = await this.request("/products", {
+            method: "POST",
+            body: { productIds, product_ids: productIds },
+        });
+        return { productIds: res.productIds ?? res.product_ids ?? [] };
+    }
+    // POST /timeline_comments — add a comment to a resource's timeline.
+    createTimelineComment(body) {
+        return this.request("/timeline_comments", { method: "POST", body });
+    }
+    // DELETE /timeline_comments/{id} — remove a timeline comment (204, no body).
+    deleteTimelineComment(id) {
+        return this.request(`/timeline_comments/${id}`, { method: "DELETE" });
+    }
+    // GET /custom_field_definitions — list definitions for an owner type.
+    // The API requires the snake_case `owner_type` query param.
+    listCustomFieldDefinitions(opts) {
+        return this.request("/custom_field_definitions", {
+            query: { owner_type: opts.ownerType, limit: opts.limit, page: opts.page },
+        });
+    }
+    // POST /custom_fields — attach a custom field value to an item or rental.
+    // Maps the camelCase input to the snake_case body the API expects.
+    createCustomField(body) {
+        return this.request("/custom_fields", {
+            method: "POST",
+            body: {
+                owner_id: body.ownerId,
+                value: body.value,
+                definition_id: body.definitionId,
+                key: body.key,
+                owner_type: body.ownerType,
+            },
+        });
+    }
+    // PUT /custom_fields/{id} — update an existing custom field's value.
+    updateCustomField(id, value) {
+        return this.request(`/custom_fields/${id}`, { method: "PUT", body: { value } });
+    }
+    // DELETE /custom_fields/{id} — remove a custom field (204, no body).
+    deleteCustomField(id) {
+        return this.request(`/custom_fields/${id}`, { method: "DELETE" });
+    }
+    // GET /custom_field_definitions/{id} — retrieve a single definition.
+    getCustomFieldDefinition(id) {
+        return this.request(`/custom_field_definitions/${id}`);
+    }
+    // GET /locations — list all locations (reference data).
+    listLocations() {
+        return this.request("/locations");
+    }
+    // GET /conditions — list all conditions (reference data).
+    listConditions() {
+        return this.request("/conditions");
+    }
+    // POST /return_orders — start a return (cycle-scoped via rentalId).
+    createReturn(body) {
+        return this.request("/return_orders", {
+            method: "POST",
+            body,
+        });
+    }
+    // GET /return_orders — list returns with optional filters.
+    listReturns(filters = {}) {
+        return this.request("/return_orders", { query: { ...filters } });
+    }
+    // Follow keyset pagination to gather every matching return. Caps the number
+    // of pages as a safety net against an unexpected server response.
+    async listAllReturns(filters = {}, maxPages = 1000) {
+        const all = [];
+        let page = filters.page;
+        for (let i = 0; i < maxPages; i++) {
+            // Sequential by design: each request needs the previous page's cursor.
+            // oxlint-disable-next-line no-await-in-loop
+            const res = await this.listReturns({ ...filters, page });
+            all.push(...res.data);
+            if (!res.nextPage) {
+                return { data: all, nextPage: null };
+            }
+            page = res.nextPage;
+        }
+        return { data: all, nextPage: null };
+    }
+    // GET /return_orders/{id} — retrieve a single return.
+    getReturn(id, options = {}) {
+        return this.request(`/return_orders/${id}`, {
+            query: { include: options.include },
+        });
+    }
+    // PUT /return_orders/{id} — update a return's status and/or line statuses.
+    updateReturn(id, body) {
+        return this.request(`/return_orders/${id}`, { method: "PUT", body });
+    }
+}

package/dist/lib/config.js

@@ -0,0 +1,38 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function configDir() {
+    const base = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+    return join(base, "supercycle");
+}
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+export function loadConfig() {
+    try {
+        const raw = readFileSync(configPath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        // Missing or unreadable config is not an error — fall back to defaults.
+        return {};
+    }
+}
+export function saveConfig(config) {
+    mkdirSync(configDir(), { recursive: true });
+    // Mode 0600: the API key is a secret, keep it readable only by the owner.
+    writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
+// Resolve the API token, preferring the environment over the config file.
+export function getToken() {
+    const fromEnv = process.env["SUPERCYCLE_API_KEY"];
+    if (fromEnv && fromEnv.trim() !== "") {
+        return fromEnv.trim();
+    }
+    return loadConfig().apiKey ?? null;
+}
+export function getBaseUrl() {
+    return process.env["SUPERCYCLE_BASE_URL"] ?? loadConfig().baseUrl ?? undefined;
+}

package/dist/lib/format.js

@@ -0,0 +1,49 @@
+export const EMPTY = "—";
+// ISO date-time → short, human-readable local string. Null/undefined → em dash.
+export function formatDateTime(value) {
+    if (!value)
+        return EMPTY;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    return date.toLocaleString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}
+// ISO date-time → short date only.
+export function formatDate(value) {
+    if (!value)
+        return EMPTY;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    return date.toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
+}
+// snake_case / lowercase enum → Title Case.
+export function titleCase(value) {
+    if (!value)
+        return EMPTY;
+    return value
+        .split(/[_\s]+/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export function customerName(customer) {
+    if (!customer)
+        return EMPTY;
+    const name = [customer.firstName, customer.lastName].filter(Boolean).join(" ").trim();
+    return name || customer.email || EMPTY;
+}
+export function dash(value) {
+    if (value === undefined || value === null || value === "")
+        return EMPTY;
+    return String(value);
+}

package/dist/lib/listViewOptions.js

@@ -0,0 +1,39 @@
+import { option } from "pastel";
+import zod from "zod";
+// Options shared by `cycles list` and the read-convenience commands
+// (to-fulfill, to-receive, overdue, today). Returned as a fresh shape each
+// call so each command gets its own zod field instances.
+export function listViewShape() {
+    return {
+        search: zod
+            .string()
+            .optional()
+            .describe(option({ description: "Filter by title or customer text" })),
+        all: zod
+            .boolean()
+            .default(false)
+            .describe(option({ description: "Fetch every page (auto-paginate)" })),
+        limit: zod
+            .number()
+            .min(1)
+            .max(100)
+            .default(50)
+            .describe(option({ description: "Results per page (1–100)" })),
+        page: zod
+            .string()
+            .optional()
+            .describe(option({ description: "Pagination cursor (from a previous run)" })),
+        json: zod
+            .boolean()
+            .default(false)
+            .describe(option({ description: "Output raw JSON" })),
+    };
+}
+// Pull the shared paging/search fields out of a command's parsed options.
+export function viewFilters(options) {
+    return {
+        search: options.search,
+        limit: options.limit,
+        page: options.page,
+    };
+}

package/dist/lib/resolveClient.js

@@ -0,0 +1,11 @@
+import { SupercycleClient } from "./client.js";
+import { getToken, getBaseUrl } from "./config.js";
+export const NO_TOKEN_HINT = "Set an API key with `supercycle login`, or the SUPERCYCLE_API_KEY environment variable.";
+// Build a client from the resolved token, or return an error if none is set.
+export function resolveClient() {
+    const token = getToken();
+    if (!token) {
+        return { error: "No Supercycle API key found." };
+    }
+    return { client: new SupercycleClient({ token, baseUrl: getBaseUrl() }) };
+}

package/dist/lib/types.js

@@ -0,0 +1,3 @@
+// Types derived from the Supercycle Admin API OpenAPI spec.
+// In the API a "cycle" is modelled as a "rental".
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@supercycle/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for the Supercycle Admin API",
+  "license": "UNLICENSED",
+  "bin": {
+    "supercycle": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ink": "^5.1.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "pastel": "^3.0.0",
+    "react": "^18.3.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "oxfmt": "^0.53.0",
+    "oxlint": "^1.68.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "fmt": "oxfmt .",
+    "fmt:check": "oxfmt --check .",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  }
+}