@skrr-ai/cli 0.1.79 → 0.1.81

package/dist/commands/store/reviews.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeReview = describeReview;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const review_1 = require("./review");
+const REVIEW_LIST_MAX = 50;
+function reviewerName(review) {
+    return review.reviewer?.displayName || review.reviewer?.username || 'a former user';
+}
+/** Plain-text lines for one written review and the publisher's reply to it. */
+function describeReview(review) {
+    const when = (review.reviewedAt || review.updatedAt || review.createdAt || '').slice(0, 10);
+    const lines = [
+        `${review.id}  ${review.rating}/${data_provider_1.STORE_AGENT_RATING_MAX}  ${(0, review_1.describeRatedRelease)(review.ratedRelease)}  by ${reviewerName(review)}${when ? `  ${when}` : ''}`,
+    ];
+    if (review.review)
+        lines.push(`  ${review.review}`);
+    const reply = review.publisherReply;
+    if (reply) {
+        lines.push(`  Publisher reply${reply.predatesReviewEdit ? ' (written before the review was last edited)' : ''}: ${reply.body}`);
+    }
+    return lines;
+}
+/**
+ * Read a Store agent's written reviews, or your own rating of it, and — as the
+ * agent's publisher — answer a review publicly.
+ *
+ * Star-only ratings are not listed; they are anonymous contributions to the
+ * average. Only the agent's author may reply, and the server decides that
+ * (`viewerIsPublisher`), not this command.
+ */
+class StoreReviews extends base_command_1.BaseCommand {
+    static description = "List a Store agent's written reviews, show your own rating, or reply to a review as its publisher";
+    static examples = [
+        '<%= config.bin %> store reviews agent_abc',
+        '<%= config.bin %> store reviews agent_abc --limit 20 --cursor <next-cursor>',
+        '<%= config.bin %> store reviews agent_abc --mine',
+        '<%= config.bin %> store reviews agent_abc --reply <review-id> --body "Fixed in 1.4.1, thanks"',
+        '<%= config.bin %> store reviews agent_abc --remove-reply <review-id>',
+    ];
+    static args = {
+        agentId: core_1.Args.string({
+            description: 'The Store agent (or, to reply, your own published agent)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        limit: core_1.Flags.integer({
+            description: `Reviews per page (max ${REVIEW_LIST_MAX})`,
+            min: 1,
+            max: REVIEW_LIST_MAX,
+        }),
+        cursor: core_1.Flags.string({ description: 'Continue from the cursor a previous page printed' }),
+        mine: core_1.Flags.boolean({
+            description: 'Show only your own rating and review of this agent',
+            exclusive: ['reply', 'remove-reply', 'limit', 'cursor'],
+        }),
+        reply: core_1.Flags.string({
+            description: 'Review id to answer publicly (the agent publisher only); needs --body',
+            exclusive: ['remove-reply', 'mine', 'limit', 'cursor'],
+            dependsOn: ['body'],
+        }),
+        body: core_1.Flags.string({
+            description: `Reply text (at most ${data_provider_1.STORE_AGENT_REVIEW_MAX_LENGTH} characters). Replaces any earlier reply`,
+            dependsOn: ['reply'],
+        }),
+        'remove-reply': core_1.Flags.string({
+            description: 'Review id whose publisher reply to withdraw (the agent publisher only)',
+            exclusive: ['reply', 'mine', 'limit', 'cursor'],
+        }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(StoreReviews);
+        const agentId = args.agentId;
+        if (flags.reply !== undefined) {
+            const body = (flags.body ?? '').trim();
+            if (!body)
+                this.error('--body is empty; a reply needs text.', { exit: 2 });
+            if (body.length > data_provider_1.STORE_AGENT_REVIEW_MAX_LENGTH) {
+                this.error(`--body is ${body.length} characters; a reply holds at most ${data_provider_1.STORE_AGENT_REVIEW_MAX_LENGTH}.`, { exit: 2 });
+            }
+            try {
+                const res = await data_provider_1.dataService.replyToAgentReview({
+                    agentId,
+                    reviewId: flags.reply,
+                    body,
+                });
+                if (flags.json) {
+                    this.log(JSON.stringify(res, null, 2));
+                    return;
+                }
+                this.log(`Replied to review ${res.review.id}.`);
+                describeReview(res.review).forEach((line) => this.log(line));
+            }
+            catch (err) {
+                this.handleApiError(err, { subject: `Replying to review ${flags.reply}` });
+            }
+            return;
+        }
+        if (flags['remove-reply'] !== undefined) {
+            try {
+                const res = await data_provider_1.dataService.deleteAgentReviewReply({
+                    agentId,
+                    reviewId: flags['remove-reply'],
+                });
+                this.log(flags.json
+                    ? JSON.stringify(res, null, 2)
+                    : `Withdrew your reply to review ${res.review.id}.`);
+            }
+            catch (err) {
+                this.handleApiError(err, { subject: `Withdrawing the reply to ${flags['remove-reply']}` });
+            }
+            return;
+        }
+        if (flags.mine) {
+            try {
+                const res = await data_provider_1.dataService.getAgentUserRating(agentId);
+                if (flags.json) {
+                    this.log(JSON.stringify(res, null, 2));
+                    return;
+                }
+                if (res.userRating == null) {
+                    this.log(`You have not rated ${agentId}. Rate it with: skrr store review ${agentId} --rating <1-5>`);
+                    return;
+                }
+                this.log(`You rated ${agentId} ${res.userRating}/${data_provider_1.STORE_AGENT_RATING_MAX} on ${(0, review_1.describeRatedRelease)(res.ratedRelease)}.`);
+                this.log(res.userReview ? `Review: ${res.userReview}` : 'No written review.');
+            }
+            catch (err) {
+                this.handleApiError(err, { subject: `Reading your rating of ${agentId}` });
+            }
+            return;
+        }
+        try {
+            const res = await data_provider_1.dataService.getStoreAgentReviews(agentId, {
+                ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+                ...(flags.cursor ? { cursor: flags.cursor } : {}),
+            });
+            if (flags.json) {
+                this.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            if (res.data.length === 0) {
+                this.log(`No written reviews of ${agentId}${flags.cursor ? ' on this page' : ''}.`);
+            }
+            res.data.forEach((review, index) => {
+                if (index > 0)
+                    this.log('');
+                describeReview(review).forEach((line) => this.log(line));
+            });
+            if (res.has_more && res.next_cursor) {
+                this.log('');
+                this.log(`More: skrr store reviews ${agentId} --cursor ${res.next_cursor}`);
+            }
+            if (res.viewerIsPublisher && res.data.length > 0) {
+                this.log('');
+                this.log(`You publish this agent. Answer a review with: skrr store reviews ${agentId} --reply <review-id> --body "..."`);
+            }
+        }
+        catch (err) {
+            this.handleApiError(err, { subject: `Listing reviews of ${agentId}` });
+        }
+    }
+}
+exports.default = StoreReviews;

package/dist/commands/store/tip.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Tip a public listing (SVC10). A tip is charged once from your balance under
+ * the fee schedule's tipping rate and grants nothing. `--tip-id` is the
+ * idempotency identity: repeat it to retry the SAME tip safely; omit it and
+ * every invocation is a new charge.
+ */
+export default class StoreTip extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        amount: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'tip-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/store/tip.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const usd_micros_1 = require("../../lib/usd-micros");
+/**
+ * Tip a public listing (SVC10). A tip is charged once from your balance under
+ * the fee schedule's tipping rate and grants nothing. `--tip-id` is the
+ * idempotency identity: repeat it to retry the SAME tip safely; omit it and
+ * every invocation is a new charge.
+ */
+class StoreTip extends base_command_1.BaseCommand {
+    static description = 'Tip the publisher of a public store listing — charged once, grants no entitlement';
+    static examples = [
+        '<%= config.bin %> store tip agent_abc123 --amount 5',
+        '<%= config.bin %> store tip agent_abc123 --amount 2.50 --tip-id my-retry-key',
+    ];
+    static args = {
+        agentId: core_1.Args.string({
+            description: 'Store listing (agent) id',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        amount: core_1.Flags.string({ description: 'Amount in USD, e.g. 5 or 2.50', required: true }),
+        'tip-id': core_1.Flags.string({
+            description: 'Idempotency key — reuse it to retry the same tip without charging twice',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(StoreTip);
+        const amountMicros = (0, usd_micros_1.usdToMicros)(flags.amount);
+        if (amountMicros === null) {
+            this.error(`--amount must be a positive USD amount with at most 2 decimals (got "${flags.amount}")`);
+        }
+        const tipId = flags['tip-id'] ?? (0, node_crypto_1.randomUUID)();
+        try {
+            const result = await data_provider_1.dataService.tipStoreAgent(args.agentId, { amountMicros, tipId });
+            if (flags.json) {
+                this.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            this.log(result.replayed
+                ? `Already tipped under ${tipId}; nothing new was charged.`
+                : `Tipped $${(result.amountMicros / 1_000_000).toFixed(2)} (tip ${tipId}).`);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+    }
+}
+exports.default = StoreTip;

package/dist/commands/tokens/create.d.ts

@@ -0,0 +1,28 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr tokens create` — mint a personal access token (`osk_pat_*`, OSK-13208)
+ * for CI. The secret is printed EXACTLY ONCE.
+ *
+ * Creating one needs a sign-in session (a token cannot mint a token) and, for
+ * an account with two-factor authentication, a fresh authenticator code from
+ * that session. `--otp` / `--backup-code` supply it up front; at a terminal the
+ * command asks for it when the server does.
+ */
+export default class TokensCreate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        name: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        name: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'expires-in-days': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        otp: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'backup-code': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private verify;
+    private refuseStepUp;
+}

package/dist/commands/tokens/create.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const access_tokens_1 = require("../../lib/access-tokens");
+const api_fetch_1 = require("../../lib/api-fetch");
+const prompt_1 = require("../../lib/prompt");
+/**
+ * `skrr tokens create` — mint a personal access token (`osk_pat_*`, OSK-13208)
+ * for CI. The secret is printed EXACTLY ONCE.
+ *
+ * Creating one needs a sign-in session (a token cannot mint a token) and, for
+ * an account with two-factor authentication, a fresh authenticator code from
+ * that session. `--otp` / `--backup-code` supply it up front; at a terminal the
+ * command asks for it when the server does.
+ */
+class TokensCreate extends base_command_1.BaseCommand {
+    static description = 'Create a personal access token for CI (use it as SKRR_TOKEN). The secret is shown once and never again.';
+    static examples = [
+        '<%= config.bin %> tokens create github-actions',
+        '<%= config.bin %> tokens create deploy --scope write --expires-in-days 30',
+        '<%= config.bin %> tokens create ci --scope write --otp 123456 --json',
+    ];
+    static args = {
+        name: core_1.Args.string({
+            description: 'Label for the token, e.g. the CI secret it will live in (also --name)',
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        name: core_1.Flags.string({ description: 'Label for the token (1-64 chars)' }),
+        scope: core_1.Flags.string({
+            description: 'read: GET requests only. write: everything the CLI can do as you, except sign-in, credential, account-deletion, admin and payment actions',
+            options: ['read', 'write'],
+            default: 'read',
+        }),
+        'expires-in-days': core_1.Flags.integer({
+            description: 'Days until the token expires (1-365)',
+            min: 1,
+            max: 365,
+            default: 90,
+        }),
+        otp: core_1.Flags.string({
+            description: 'Current code from your authenticator app, if your account uses two-factor',
+            exclusive: ['backup-code'],
+        }),
+        'backup-code': core_1.Flags.string({
+            description: 'One of your unused backup codes (it is spent)',
+            exclusive: ['otp'],
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON (includes the secret)' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TokensCreate);
+        const name = flags.name || args.name;
+        if (!name) {
+            this.error('A name is required — pass it positionally or with --name.', { exit: 1 });
+        }
+        const input = {
+            name,
+            scopes: [flags.scope],
+            expiresInDays: flags['expires-in-days'],
+        };
+        let code = null;
+        if (flags.otp)
+            code = { token: flags.otp.trim() };
+        else if (flags['backup-code'])
+            code = { backupCode: flags['backup-code'].trim() };
+        if (code)
+            await this.verify(code);
+        let created;
+        try {
+            created = await (0, access_tokens_1.createAccessToken)(input);
+        }
+        catch (err) {
+            const challenge = stepUpChallenge(err);
+            if (!challenge)
+                return this.handleApiError(err);
+            if (code || challenge.reason !== 'no_recent_step_up') {
+                return this.refuseStepUp(challenge);
+            }
+            if (!process.stdin.isTTY) {
+                return this.refuseStepUp(challenge);
+            }
+            const entered = (await (0, prompt_1.prompt)('Code from your authenticator app: ')).trim();
+            code = { token: entered };
+            await this.verify(code);
+            try {
+                created = await (0, access_tokens_1.createAccessToken)(input);
+            }
+            catch (retryErr) {
+                return this.handleApiError(retryErr);
+            }
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(created, null, 2));
+            return;
+        }
+        const t = created.accessToken;
+        this.log('');
+        this.log(`  ${created.token}`);
+        this.log('');
+        this.log('This is the only time the token will be displayed. Store it as a CI secret now.');
+        this.log(`Use it as:  SKRR_TOKEN=<token> ${this.config.bin} <command>`);
+        this.log('');
+        this.log(`  id       ${t.id}`);
+        this.log(`  name     ${t.name}`);
+        this.log(`  scopes   ${t.scopes.join(', ')}`);
+        this.log(`  expires  ${t.expiresAt ?? '(unknown)'}`);
+    }
+    async verify(code) {
+        try {
+            await data_provider_1.dataService.verifyStepUp({ purpose: data_provider_1.ACCESS_TOKEN_CREATE_STEP_UP_PURPOSE, ...code });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+    }
+    refuseStepUp(challenge) {
+        const bin = this.config.bin;
+        const messages = {
+            credential_not_session_bound: `Creating an access token needs a sign-in session, and this credential is not one (an access token cannot create another). Run \`${bin} login\` and try again. Nothing changed.`,
+            two_factor_not_enabled: 'Creating an access token needs two-factor authentication on this account. Turn it on in the web app, then try again. Nothing changed.',
+            no_recent_step_up: 'Creating an access token needs a fresh code from your authenticator app. Run this command again with --otp <code> (or --backup-code <code>). Nothing changed.',
+        };
+        this.error(messages[challenge.reason], { code: 'STEP_UP_REQUIRED', exit: 2 });
+    }
+}
+exports.default = TokensCreate;
+function stepUpChallenge(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError) || err.status !== 403)
+        return null;
+    return (0, data_provider_1.stepUpChallengeFromError)(err);
+}

package/dist/commands/tokens/list.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command';
+/** `skrr tokens list` — your personal access tokens (never their secrets). */
+export default class TokensList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        all: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tokens/list.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const access_tokens_1 = require("../../lib/access-tokens");
+/** `skrr tokens list` — your personal access tokens (never their secrets). */
+class TokensList extends base_command_1.BaseCommand {
+    static description = 'List your personal access tokens (secrets are never shown again)';
+    static examples = [
+        '<%= config.bin %> tokens list',
+        '<%= config.bin %> tokens list --all',
+        '<%= config.bin %> tokens list --json',
+    ];
+    static flags = {
+        all: core_1.Flags.boolean({ description: 'Include revoked and expired tokens' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(TokensList);
+        let tokens;
+        try {
+            tokens = await (0, access_tokens_1.listAccessTokens)();
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        const shown = flags.all ? tokens : tokens.filter((t) => t.state === 'active');
+        if (flags.json) {
+            this.log(JSON.stringify({ accessTokens: shown }, null, 2));
+            return;
+        }
+        if (shown.length === 0) {
+            this.log(flags.all || tokens.length === 0
+                ? `No access tokens. Create one with \`${this.config.bin} tokens create <name>\`.`
+                : `No active access tokens (${tokens.length} revoked or expired; --all shows them).`);
+            return;
+        }
+        for (const t of shown) {
+            this.log([
+                t.id,
+                t.name,
+                `…${t.lastFour}`,
+                t.scopes.join('+'),
+                (0, access_tokens_1.describeAccessTokenState)(t),
+                `expires ${t.expiresAt ?? '?'}`,
+                `last used ${t.lastUsedAt ?? 'never'}`,
+            ].join('  '));
+        }
+    }
+}
+exports.default = TokensList;

package/dist/commands/tokens/revoke.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base-command';
+/** `skrr tokens revoke <id>` — irreversible; a revoked token is replaced, never re-enabled. */
+export default class TokensRevoke extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        compromised: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tokens/revoke.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const access_tokens_1 = require("../../lib/access-tokens");
+/** `skrr tokens revoke <id>` — irreversible; a revoked token is replaced, never re-enabled. */
+class TokensRevoke extends base_command_1.BaseCommand {
+    static description = 'Revoke a personal access token. Anything still presenting it is refused on its next request.';
+    static examples = [
+        '<%= config.bin %> tokens revoke <token-id>',
+        '<%= config.bin %> tokens revoke <token-id> --compromised',
+    ];
+    static args = {
+        id: core_1.Args.string({
+            description: 'Token id (from `tokens list`)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        compromised: core_1.Flags.boolean({ description: 'Record that the token leaked' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TokensRevoke);
+        try {
+            const res = await (0, access_tokens_1.revokeAccessToken)(args.id, { compromised: flags.compromised });
+            if (flags.json) {
+                this.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            this.log(res.alreadyRevoked
+                ? `${args.id} was already revoked.`
+                : `Revoked ${args.id}. Anything still presenting it will now be refused.`);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+    }
+}
+exports.default = TokensRevoke;

package/dist/lib/access-tokens.d.ts

@@ -0,0 +1,59 @@
+/**
+ * access-tokens.ts — request client for `/api/user/access-tokens`, the
+ * personal access tokens (`osk_pat_*`, OSK-13208) behind `skrr tokens`.
+ *
+ * A personal access token is how CI runs `skrr` AS a person: set it as
+ * `SKRR_TOKEN` and every command authenticates with it, never refreshing,
+ * until it expires or is revoked. It is not `skrr create-token` (an `osk_ci_`
+ * DAEMON bootstrap token), not `skrr token mint` (a rotating refresh bundle),
+ * and not `skrr api-keys` (Space-scoped Managed-Agents keys).
+ *
+ * Path literals are inline on purpose: `domain-api-parity` resolves a command
+ * to an endpoint by reading these strings.
+ */
+/** A token as the API returns it. The secret is never part of this shape. */
+export interface AccessToken {
+    id: string;
+    name: string;
+    lastFour: string;
+    scopes: string[];
+    /** Derived server-side: natural expiry is not stored as a revocation. */
+    state: 'active' | 'expired' | 'revoked';
+    createdAt: string | null;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    revokedReason: string | null;
+    createdFromIp: string | null;
+    createdFromUserAgent: string | null;
+}
+/** The create response. `token` is shown exactly once and never again. */
+export interface AccessTokenCreated {
+    token: string;
+    accessToken: AccessToken;
+}
+export interface CreateAccessTokenInput {
+    name: string;
+    scopes?: string[];
+    expiresInDays?: number;
+}
+/**
+ * The words for each stored revocation reason. Every member of the schema's
+ * `revokedReason` enum appears here, so the list shows WHY a token died —
+ * "revoked" alone cannot tell a deliberate revoke from a sign-out sweep.
+ */
+export declare const ACCESS_TOKEN_REVOKED_REASON_LABELS: Record<string, string>;
+export declare function createAccessToken(input: CreateAccessTokenInput): Promise<AccessTokenCreated>;
+/** Every token the caller owns, newest first, including revoked and expired rows. */
+export declare function listAccessTokens(): Promise<AccessToken[]>;
+export interface RevokeAccessTokenResult {
+    revoked: boolean;
+    alreadyRevoked: boolean;
+    accessToken?: AccessToken;
+}
+/** Revoke one token. Irreversible: a revoked token is replaced, never re-enabled. */
+export declare function revokeAccessToken(id: string, opts?: {
+    compromised?: boolean;
+}): Promise<RevokeAccessTokenResult>;
+/** One-line status for a listed token. */
+export declare function describeAccessTokenState(token: AccessToken): string;

package/dist/lib/access-tokens.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCESS_TOKEN_REVOKED_REASON_LABELS = void 0;
+exports.createAccessToken = createAccessToken;
+exports.listAccessTokens = listAccessTokens;
+exports.revokeAccessToken = revokeAccessToken;
+exports.describeAccessTokenState = describeAccessTokenState;
+const api_fetch_1 = require("./api-fetch");
+/**
+ * The words for each stored revocation reason. Every member of the schema's
+ * `revokedReason` enum appears here, so the list shows WHY a token died —
+ * "revoked" alone cannot tell a deliberate revoke from a sign-out sweep.
+ */
+exports.ACCESS_TOKEN_REVOKED_REASON_LABELS = {
+    user: 'revoked by you',
+    sign_out_everywhere: 'revoked by sign-out everywhere / password or 2FA change',
+    admin: 'revoked by an administrator',
+    compromised: 'revoked as compromised',
+};
+async function createAccessToken(input) {
+    return (0, api_fetch_1.apiFetch)('/api/user/access-tokens', {
+        method: 'POST',
+        body: {
+            name: input.name,
+            ...(input.scopes ? { scopes: input.scopes } : {}),
+            ...(input.expiresInDays !== undefined ? { expiresInDays: input.expiresInDays } : {}),
+        },
+    });
+}
+/** Every token the caller owns, newest first, including revoked and expired rows. */
+async function listAccessTokens() {
+    const res = await (0, api_fetch_1.apiFetch)('/api/user/access-tokens');
+    return Array.isArray(res?.accessTokens) ? res.accessTokens : [];
+}
+/** Revoke one token. Irreversible: a revoked token is replaced, never re-enabled. */
+async function revokeAccessToken(id, opts = {}) {
+    return (0, api_fetch_1.apiFetch)(`/api/user/access-tokens/${encodeURIComponent(id)}`, {
+        method: 'DELETE',
+        ...(opts.compromised ? { body: { reason: 'compromised' } } : {}),
+    });
+}
+/** One-line status for a listed token. */
+function describeAccessTokenState(token) {
+    if (token.state === 'revoked') {
+        return exports.ACCESS_TOKEN_REVOKED_REASON_LABELS[token.revokedReason ?? ''] ?? 'revoked';
+    }
+    if (token.state === 'expired')
+        return 'expired';
+    return 'active';
+}