@shardflux/sdk 0.7.0 → 0.9.0

package/dist/executions.js

@@ -0,0 +1,99 @@
+/** `^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$` (cell-api.yaml ExecutionIdValue). */
+export const EXECUTION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+/** A fresh execution id: `ex-` plus a random UUID (39 characters, valid per EXECUTION_ID). */
+export function newExecutionId() {
+    return `ex-${crypto.randomUUID()}`;
+}
+const bytes = (s) => (s ? new Uint8Array(Buffer.from(s, 'base64')) : new Uint8Array());
+/** The outcome of an execution: decoded output, exit status, the revision it produced and what it changed. */
+export class ExecutionResult {
+    executionId;
+    state;
+    /** The tree revision the command ran on. */
+    baseRevision;
+    /**
+     * The tree revision after the execution: `baseRevision + 1` when it changed files, else `baseRevision`; null unless
+     * `state` is `succeeded` (a failed or lost execution publishes nothing).
+     */
+    treeRevision;
+    /** The command's exit status (-1 when a signal ended it); null unless succeeded. */
+    exitCode;
+    termSignal;
+    /** The command ran past `timeoutMs` and was killed. */
+    timedOut;
+    /** Standard output, at most `outputLimitBytes`. */
+    stdout;
+    stderr;
+    stdoutTruncated;
+    stderrTruncated;
+    /** What the execution changed under /home/user, sorted by path (at most 10 000; see `changedTruncated`). */
+    changed;
+    changedTruncated;
+    /** Milliseconds and counts: queue_ms, run_ms, publish_ms, total_ms and the host's (boot_ms, exec_ms, vm_seconds, ...). */
+    timings;
+    /** failed / lost: why (`details.reason`); null otherwise. */
+    error;
+    createdAt;
+    finishedAt;
+    /**
+     * The call that returned this result did not start the execution: `executions.run()` answered 200 (the execution
+     * already existed: its recorded result, or the running one waited for), or it came from `executions.get()`. False
+     * only for the run() call whose request started it (201).
+     */
+    replayed;
+    /** The body as the cell sent it. */
+    raw;
+    constructor(body, replayed) {
+        this.raw = body;
+        this.executionId = body.execution_id;
+        this.state = body.state;
+        this.baseRevision = body.base_revision;
+        this.treeRevision = body.tree_revision ?? null;
+        this.exitCode = body.exit_code ?? null;
+        this.termSignal = body.term_signal ?? null;
+        this.timedOut = body.timed_out === true;
+        this.stdout = bytes(body.stdout);
+        this.stderr = bytes(body.stderr);
+        this.stdoutTruncated = body.stdout_truncated === true;
+        this.stderrTruncated = body.stderr_truncated === true;
+        this.changed = body.changed ?? [];
+        this.changedTruncated = body.changed_truncated === true;
+        this.timings = body.timings ?? {};
+        const e = body.error;
+        this.error =
+            e && typeof e === 'object' && typeof e.code === 'string'
+                ? {
+                    code: e.code,
+                    message: typeof e.message === 'string' ? e.message : '',
+                    retryable: e.retryable === true,
+                    ...(typeof e.details === 'object' && e.details !== null ? { details: e.details } : {}),
+                }
+                : null;
+        this.createdAt = body.created_at;
+        this.finishedAt = body.finished_at ?? null;
+        this.replayed = replayed;
+    }
+    /** Still queued or running (only `executions.get()` returns such a result). */
+    get pending() {
+        return this.state === 'queued' || this.state === 'running';
+    }
+    /** The command ran to its end with exit code 0. */
+    get ok() {
+        return this.state === 'succeeded' && this.exitCode === 0;
+    }
+    /** A stream as text (UTF-8; invalid sequences become U+FFFD). */
+    text(stream = 'stdout') {
+        return new TextDecoder().decode(stream === 'stderr' ? this.stderr : this.stdout);
+    }
+    get stdoutText() {
+        return this.text('stdout');
+    }
+    get stderrText() {
+        return this.text('stderr');
+    }
+    /** `error.details.reason` of a failed or lost execution (null otherwise). */
+    get errorReason() {
+        const r = this.error?.details?.reason;
+        return typeof r === 'string' ? r : null;
+    }
+}

package/dist/feedback.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Product feedback (POST /v1/feedback, 0.9.0+): a short message from the customer or their coding agent that goes
+ * straight to the Shardflux founder by email.
+ *
+ *   await cloud.sendFeedback({ message: 'open took 40 s on python-node-browser', category: 'bug', context: { requestId: err.requestId } });
+ *
+ * Any valid API key may send (no tool permission needed). The server bounds it per key (429 `rate_limited`,
+ * `retryAfterSeconds` on the error; the SDK never retries it) and folds a repeat of the same message within 24 hours
+ * into the first one (`duplicate: true`, no second email). An empty or over-long message, an unknown category or an
+ * over-long context field is 422 `validation_failed`. Anything shaped like an API key is redacted server side.
+ *
+ * The request and response types are written by hand until the generated contract (src/generated/app-api.ts) has the
+ * route; type-checks.ts then pins them to it.
+ */
+import type { ClientContext } from './client.js';
+/**
+ * bug: something failed or behaved wrongly. confusing: an error, doc, name or output was unclear or misleading.
+ * missing: a capability, option or template you needed does not exist. idea: a suggestion or improvement.
+ * praise: something worked well. other (the server's default).
+ */
+export type FeedbackCategory = 'bug' | 'confusing' | 'missing' | 'idea' | 'praise' | 'other';
+/** Every category, in the order the help texts list them. */
+export declare const FEEDBACK_CATEGORIES: readonly FeedbackCategory[];
+/** Longest message the API accepts, in characters after trimming (it must also contain a non-whitespace character). */
+export declare const FEEDBACK_MESSAGE_MAX_LENGTH = 8000;
+/** What the feedback is about, so the founder can find the logs. Every field is optional text. */
+export interface FeedbackContext {
+    /** Who is reporting: e.g. `claude-code`, `codex`, `cursor`, or a person (<= 100 characters). */
+    agent?: string;
+    /** Client and version (<= 200). Default: `shardflux-sdk-ts/<SDK_VERSION>`. */
+    client?: string;
+    /** Workspace id or key the feedback is about (<= 200). */
+    workspace?: string;
+    /** `requestId` of the ShardfluxApiError that prompted it (<= 200). */
+    requestId?: string;
+    /** The API error code seen, e.g. `capacity_unavailable` (<= 100). */
+    errorCode?: string;
+    /** The command, SDK call or tool call that led to it (<= 2000). */
+    command?: string;
+    /** Dashboard route (<= 300); browser clients only in practice. */
+    page?: string;
+}
+export interface SendFeedbackParams {
+    /** 1-8000 characters after trimming. Short and specific: what you did, what happened, what you expected. */
+    message: string;
+    /** Default (server side) `other`. */
+    category?: FeedbackCategory;
+    context?: FeedbackContext;
+}
+/**
+ * Feedback sent with a CLI user session (`ShardfluxAccount.sendFeedback`, 0.9.0+): as the signed-in user, optionally
+ * about one of their organizations. A project API key cannot name an organization (its own is used).
+ */
+export interface AccountFeedbackParams extends SendFeedbackParams {
+    /** One of the signed-in user's organizations (404 `not_found` otherwise). */
+    organizationId?: string;
+}
+/** The stored feedback. */
+export interface FeedbackReceipt {
+    id: string;
+    /** RFC 3339. For a duplicate, when the original was received. */
+    receivedAt: string;
+    /** The same message from the same key within 24 hours: the original is returned and no second email is sent. */
+    duplicate: boolean;
+}
+/** POST /v1/feedback with the context's credential (API key or CLI session). 201 (new) and 200 (duplicate) carry the same body. */
+export declare function sendFeedback(ctx: ClientContext, params: AccountFeedbackParams): Promise<FeedbackReceipt>;

package/dist/feedback.js

@@ -0,0 +1,39 @@
+import { ShardfluxProtocolError } from "./errors.js";
+import { SDK_VERSION } from "./http.js";
+/** Every category, in the order the help texts list them. */
+export const FEEDBACK_CATEGORIES = ['bug', 'confusing', 'missing', 'idea', 'praise', 'other'];
+/** Longest message the API accepts, in characters after trimming (it must also contain a non-whitespace character). */
+export const FEEDBACK_MESSAGE_MAX_LENGTH = 8000;
+const CONTEXT_FIELDS = [
+    ['agent', 'agent'],
+    ['client', 'client'],
+    ['workspace', 'workspace'],
+    ['requestId', 'request_id'],
+    ['errorCode', 'error_code'],
+    ['command', 'command'],
+    ['page', 'page'],
+];
+/** The request body: context fields in snake_case, `client` defaulted to this SDK. */
+function feedbackBody(params) {
+    const context = {};
+    for (const [from, to] of CONTEXT_FIELDS) {
+        const v = params.context?.[from];
+        if (v !== undefined)
+            context[to] = v;
+    }
+    context.client ??= `shardflux-sdk-ts/${SDK_VERSION}`;
+    return {
+        message: params.message,
+        ...(params.category !== undefined ? { category: params.category } : {}),
+        ...(params.organizationId !== undefined ? { organization_id: params.organizationId } : {}),
+        context,
+    };
+}
+/** POST /v1/feedback with the context's credential (API key or CLI session). 201 (new) and 200 (duplicate) carry the same body. */
+export async function sendFeedback(ctx, params) {
+    const { status, body } = await ctx.http.jsonWithStatus('POST', '/v1/feedback', { json: feedbackBody(params) }, ctx.authorization);
+    if (typeof body?.id !== 'string' || typeof body.received_at !== 'string' || typeof body.duplicate !== 'boolean') {
+        throw new ShardfluxProtocolError('POST /v1/feedback: the response is not {id, received_at, duplicate}', status);
+    }
+    return { id: body.id, receivedAt: body.received_at, duplicate: body.duplicate };
+}