flypod 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,6 +15,8 @@ interface RequestInit {
15
15
  json?: unknown;
16
16
  zip?: Uint8Array;
17
17
  query?: Record<string, string | undefined>;
18
+ /** Headers for this one request, on top of the client's own. */
19
+ headers?: Record<string, string>;
18
20
  }
19
21
  export interface FlypodClient {
20
22
  readonly baseUrl: string;
@@ -33,7 +35,10 @@ export interface FlypodClient {
33
35
  manage_token: string;
34
36
  }>): Promise<Response>;
35
37
  getSite(siteId: string): Promise<Response>;
36
- createSite(zip: Uint8Array): Promise<Response>;
38
+ /** `relink`: this folder already deployed to another site (`x-flypod-relink`). */
39
+ createSite(zip: Uint8Array, opts?: {
40
+ relink?: boolean;
41
+ }): Promise<Response>;
37
42
  redeploy(siteId: string, zip: Uint8Array): Promise<Response>;
38
43
  rollback(siteId: string, versionId: string): Promise<Response>;
39
44
  setTimeline(siteId: string, enabled: boolean): Promise<Response>;
@@ -79,7 +84,11 @@ export declare function resolveCredentials(env: NodeJS.ProcessEnv, session: CliS
79
84
  export declare function buildClient(token: string | undefined, baseUrl: string, fetchImpl: FetchLike,
80
85
  /** Deploy attribution. Defaults to `library`: the only callers that build a
81
86
  * client without saying so are library embedders (see src/cli.ts). */
82
- source?: DeploySource): FlypodClient;
87
+ source?: DeploySource,
88
+ /** Sent on every request. Only `createClient` passes any (install id and
89
+ * CLI version); a library caller gets none, so `deploySite` stays free of
90
+ * anything that identifies the machine it runs on. */
91
+ extraHeaders?: Record<string, string>): FlypodClient;
83
92
  /**
84
93
  * Build a client with credentials resolved once (a saved session is loaded
85
94
  * from disk, so this is async). `opts.fetch`/`opts.env` are the same
@@ -88,7 +97,10 @@ source?: DeploySource): FlypodClient;
88
97
  *
89
98
  * The deploy source is resolved here too (see ./source.ts) so that every
90
99
  * command routed through the CLI — not just `deploy` — reports the surface it
91
- * came from without each one having to remember.
100
+ * came from without each one having to remember. So are the install id and
101
+ * CLI version (see ./install-id.ts), for the same reason: the server can only
102
+ * tell one person's tenth deploy from ten people's first if every request
103
+ * says which install sent it.
92
104
  */
93
105
  export declare function createClient(opts: {
94
106
  env?: NodeJS.ProcessEnv;
@@ -1,5 +1,12 @@
1
+ import type { CLI_ERROR_CODES } from "../cli-error-codes";
1
2
  import type { CommandIO } from "./commands";
2
- export type ErrorCode = "usage" | "unknown_command" | "unknown_flag" | "no_build_dir" | "no_files" | "no_site" | "no_token" | "not_signed_in" | "unauthorized" | "token_rejected" | "not_found" | "no_such_version" | "site_gone" | "already_claimed" | "invalid_upload" | "too_large" | "blocked" | "challenge_required" | "rate_limited" | "server_error" | "bad_request" | "network" | "interactive_login_required" | "authorization_pending" | "login_denied" | "login_expired" | "login_timeout" | "unexpected";
3
+ export { CLI_ERROR_CODES } from "../cli-error-codes";
4
+ /**
5
+ * Every code a CLI failure can carry, grouped in `CLI_ERROR_CODES` by where it
6
+ * comes from. The list is a value in its own module so the control plane can
7
+ * validate failure reports against it without bundling the CLI.
8
+ */
9
+ export type ErrorCode = (typeof CLI_ERROR_CODES)[number];
3
10
  export interface CliError {
4
11
  code: ErrorCode;
5
12
  /** Human-readable reason. Free text; agents branch on `code` instead. */
@@ -10,6 +17,12 @@ export interface CliError {
10
17
  status?: number;
11
18
  /** Extra machine-readable fields merged into the JSON envelope. */
12
19
  extra?: Record<string, unknown>;
20
+ /**
21
+ * Fields for the failure report only (./telemetry.ts), never printed: the
22
+ * upload's shape and folder markers, in counts and fixed words. Kept apart
23
+ * from `extra` so the `--json` envelope does not grow a field per metric.
24
+ */
25
+ telemetry?: Record<string, unknown>;
13
26
  }
14
27
  export declare function exitCodeFor(code: ErrorCode): number;
15
28
  /** The wire shape, exactly as it is written to stdout under `--json`. */
@@ -45,6 +58,10 @@ export declare function readServerMessage(res: Response): Promise<{
45
58
  message: string;
46
59
  code?: string;
47
60
  json?: boolean;
61
+ /** The server's own next step, when its answer carried one. */
62
+ fix?: string;
63
+ /** Which limit a 413 hit (`files`, `total_bytes`, …), when the server said. */
64
+ limit?: string;
48
65
  }>;
49
66
  export interface ClassifyContext {
50
67
  /** `flypod update`, `flypod comments post`, … — for the human prefix. */
@@ -58,8 +75,16 @@ export interface ClassifyContext {
58
75
  * Turn a non-2xx response into a `CliError` with a stable code and a fix.
59
76
  * The server's own `code` wins when it sends one (e.g. `token_rejected`);
60
77
  * otherwise the status decides.
78
+ *
79
+ * The server's `fix` wins over the CLI's, for every code. The CLI's fixes are
80
+ * written per status and can only guess (a 413 used to say "shrink the build"
81
+ * whether the build was a project root, a folder of videos or 2 MB of source
82
+ * maps); the server has the upload in hand and can say which. It also lets a
83
+ * better answer reach every installed CLI without waiting for an upgrade.
61
84
  */
62
85
  export declare function classifyResponse(res: Response, ctx: ClassifyContext): Promise<CliError>;
86
+ /** The limits a `too_large` can name, in the CLI's precheck and in a report. */
87
+ export declare const SIZE_LIMITS: readonly ["files", "total_bytes", "zip_bytes"];
63
88
  /**
64
89
  * No folder to deploy. `resolveDeployDir` throws one long sentence (it is a
65
90
  * library function and its message has to stand alone); here it is split into
@@ -0,0 +1,38 @@
1
+ export declare const INSTALL_HEADER = "x-flypod-install";
2
+ export declare const INSTALL_NEW_HEADER = "x-flypod-install-new";
3
+ export declare const VERSION_HEADER = "x-flypod-version";
4
+ export declare const RELINK_HEADER = "x-flypod-relink";
5
+ /**
6
+ * True when the user asked not to be counted. `DO_NOT_TRACK` counts when set
7
+ * to anything but an explicit "no" (`""`, `0`, `false`), because the
8
+ * convention is "set it to turn tracking off" and people write `=1`, `=yes`
9
+ * and `=true` alike.
10
+ */
11
+ export declare function telemetryOptedOut(env: NodeJS.ProcessEnv): boolean;
12
+ export declare function installFilePath(env?: NodeJS.ProcessEnv): string;
13
+ export interface InstallId {
14
+ id: string;
15
+ /** True only in the process that created the id: the server's "new install" signal. */
16
+ isNew: boolean;
17
+ }
18
+ /**
19
+ * This machine's install id, created on first use. Null when opted out, or
20
+ * when the config directory cannot be written: no id is better than a fresh
21
+ * one every run, which would count one person as a new install each time.
22
+ * Never throws: nothing about counting may fail a deploy.
23
+ */
24
+ export declare function installId(env?: NodeJS.ProcessEnv): Promise<InstallId | null>;
25
+ export declare function setCliVersion(v: string): void;
26
+ export declare function cliVersion(): string | undefined;
27
+ /**
28
+ * The headers that say which install and which CLI version is calling. The
29
+ * version is not identifying and is always sent (when known); the install
30
+ * headers follow the opt-out.
31
+ */
32
+ export declare function identityHeaders(env: NodeJS.ProcessEnv): Promise<Record<string, string>>;
33
+ /**
34
+ * The one line a person sees the first time an id is made, so being counted
35
+ * is never a surprise. One line because the default output is short, and it
36
+ * names the switch rather than a page to read.
37
+ */
38
+ export declare const FIRST_RUN_NOTICE = "flypod counts deploys with a random id. DO_NOT_TRACK=1 stops it.";
@@ -1,7 +1,29 @@
1
1
  import type { UploadLimits } from "../ingest-error";
2
2
  import type { CliError } from "./errors";
3
+ /**
4
+ * What a failure report says about an upload: its shape by kind of byte, what
5
+ * its top level looks like, and the archive size. Counts and fixed words
6
+ * only; see ../upload-shape.ts for why no names.
7
+ */
8
+ export declare function uploadReport(files: Record<string, Uint8Array>, skippedCount?: number): Record<string, unknown>;
3
9
  /**
4
10
  * `too_large` with the limit and the biggest files named, or null when the
5
11
  * build fits or the limits are unknown (`uploadLimitsFor` returned null).
12
+ *
13
+ * The fix is `sizeAdvice` when the upload's shape says something specific
14
+ * (a project root instead of its build folder, source maps, video): "remove
15
+ * the largest files" was true of every one of them and got none deployed.
16
+ */
17
+ export declare function checkUploadSize(files: Record<string, Uint8Array>, limits: UploadLimits | null, skippedCount?: number): CliError | null;
18
+ /**
19
+ * Sharpen a `no_build_dir` / `no_files` failure with what the current folder
20
+ * looks like. When it is a project root (a package.json and no index.html),
21
+ * the fix names its build folder, or says to build first when it has none,
22
+ * because that is the whole answer and the generic "pass the folder of built
23
+ * files" made people guess which one. Adds the folder markers to the failure
24
+ * report either way. Never throws, never makes the error worse.
25
+ *
26
+ * `deployed` is the folder that turned out empty (for `no_files`), so the fix
27
+ * never names the folder that just failed.
6
28
  */
7
- export declare function checkUploadSize(files: Record<string, Uint8Array>, limits: UploadLimits | null): CliError | null;
29
+ export declare function withFolderHint(err: CliError, cwd: string, deployed?: string): Promise<CliError>;
@@ -126,10 +126,17 @@ export interface InstallSkillArgs {
126
126
  dryRun?: boolean;
127
127
  /** Project root. Defaults to cwd; tests inject. */
128
128
  cwd?: string;
129
+ /**
130
+ * One line of JSON on stdout and nothing on stderr, like every other verb.
131
+ * `install skill` used to accept `--json` and ignore it, printing
132
+ * tab-separated rows and prose instead, so an agent that installed the
133
+ * skill had nothing to parse.
134
+ */
135
+ json?: boolean;
129
136
  /**
130
137
  * A picker for interactive use. Given the plan, returns the chosen target
131
138
  * ids, or null if the user cancelled. Omitted in non-interactive contexts.
132
139
  */
133
140
  picker?: (plan: PlanEntry[]) => Promise<string[] | null>;
134
141
  }
135
- export declare function installSkill(args: InstallSkillArgs, io: CommandIO): Promise<number>;
142
+ export declare function installSkill(args: InstallSkillArgs, callerIo: CommandIO): Promise<number>;
@@ -0,0 +1,38 @@
1
+ import type { CliError } from "./errors";
2
+ type FetchLike = typeof fetch;
3
+ export declare const REPORT_TIMEOUT_MS = 1500;
4
+ export declare const TELEMETRY_PATH = "/telemetry/cli";
5
+ /** Turn reports on for this process. Called once by bin/deploy.ts; tests inject. */
6
+ export declare function startFailureReports(opts: {
7
+ verb: string;
8
+ /** `--help` anywhere on the line: nothing this run does is a failure worth counting. */
9
+ help?: boolean;
10
+ env?: NodeJS.ProcessEnv;
11
+ fetch?: FetchLike;
12
+ cwd?: string;
13
+ stdoutIsTTY?: boolean;
14
+ }): void;
15
+ /** Turn reports off again (tests). */
16
+ export declare function stopFailureReports(): void;
17
+ /**
18
+ * Queue the report for a failure that has just been shown. Returns at once;
19
+ * the request runs in the background until `flushFailureReports`.
20
+ */
21
+ export declare function reportFailure(err: CliError, args: {
22
+ json?: boolean;
23
+ }): void;
24
+ /**
25
+ * Wait for queued reports, bounded. Each one aborts itself at
26
+ * REPORT_TIMEOUT_MS; the outer timer is for a transport that ignores the
27
+ * abort signal, so exit is never held past it.
28
+ */
29
+ export declare function flushFailureReports(): Promise<void>;
30
+ /**
31
+ * The report for one failure: the code and where it happened, plus whatever
32
+ * the failure carries in `telemetry` (the upload's shape for `too_large`,
33
+ * folder markers for `no_files` / `no_build_dir`). Only strings, finite
34
+ * numbers and booleans pass, so a null in a shape never becomes a field the
35
+ * server has to reject the whole report over.
36
+ */
37
+ export declare function reportBody(err: CliError, verb: string, agent: boolean): Record<string, unknown>;
38
+ export {};
@@ -0,0 +1,8 @@
1
+ export declare const CLI_ERROR_CODES: readonly ["usage", "unknown_command", "unknown_flag", "no_build_dir", "no_files", "no_site", "no_token", "not_signed_in", "unauthorized", "token_rejected", "not_found", "no_such_version", "site_gone", "already_claimed", "invalid_upload", "too_large", "blocked", "challenge_required", "rate_limited", "server_error", "bad_request", "network", "interactive_login_required", "authorization_pending", "login_denied", "login_expired", "login_timeout", "unexpected"];
2
+ /**
3
+ * The verbs a failure report may name: `SUBCOMMANDS` in bin/deploy.ts, which
4
+ * already includes `deploy`. Copied rather than imported for the same reason
5
+ * as the codes; `test/cli-telemetry.test.ts` holds the two lists equal.
6
+ * `--help` and a deploy path are not verbs: a failed deploy reports `deploy`.
7
+ */
8
+ export declare const CLI_VERBS: readonly ["deploy", "update", "versions", "rollback", "forget", "token", "login", "logout", "list", "claim", "install", "comments"];
package/dist/src/cli.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type DeploySource } from "./deploy-source";
2
+ export type { DeploySource } from "./deploy-source";
2
3
  /**
3
4
  * Build-output folders the common frontend frameworks emit, in priority order.
4
5
  * `public` ranks low because some tools use it for *source* assets (Vite/CRA);
package/dist/src/cli.js CHANGED
@@ -7,7 +7,7 @@ import {
7
7
  collectFiles,
8
8
  deploySite,
9
9
  resolveDeployDir
10
- } from "../cli-8h0vc7g2.js";
10
+ } from "../cli-z3p9tds1.js";
11
11
  export {
12
12
  BUILD_DIR_CANDIDATES,
13
13
  DEFAULT_IGNORES,
@@ -37,6 +37,16 @@ export declare const INTERNAL_COOKIE = "flypod_internal";
37
37
  * every id that ever sent one (`scripts/growth-report.ts`, `notSelf`).
38
38
  */
39
39
  export declare function isInternal(request: Request): boolean;
40
+ /**
41
+ * The X (Twitter) ad click id, kept by the landing page and the docs when a
42
+ * visitor arrives with `?twclid=` (apps/site/src/components/Analytics.astro,
43
+ * apps/docs/app/posthog-provider.tsx). A first-party cookie on .flypod.dev, so
44
+ * the sign-up or demo deploy that follows, on flypod.dev itself, carries it.
45
+ * X's own pixel keeps the same id as `_twclid`; either is accepted.
46
+ */
47
+ export declare const AD_CLICK_COOKIE = "flypod_twclid";
48
+ /** The X click id this request carries, if any. Bounded and charset-checked. */
49
+ export declare function adClickId(request: Request): string | undefined;
40
50
  /**
41
51
  * `ci` is ours, and it exists so the growth report can subtract us from our own
42
52
  * numbers. Set `FLYPOD_SOURCE=ci` in anything that deploys on our behalf — a
@@ -66,6 +76,16 @@ export declare const CLIENT_FAMILIES: readonly ["curl", "node", "bun", "deno", "
66
76
  export type ClientFamily = (typeof CLIENT_FAMILIES)[number];
67
77
  /** Reduce a `User-Agent` header to a `ClientFamily`. Never returns the input. */
68
78
  export declare function clientFamily(userAgent: string | null | undefined): ClientFamily;
79
+ /**
80
+ * Both halves of "where did this request come from": our surface (validated
81
+ * against the allowlist, so arbitrary header text never becomes a property),
82
+ * and the kind of program that made the call. See `clientFamily` for why the
83
+ * second is a fixed word and never the user agent.
84
+ */
85
+ export declare function surfaceOf(request: Request): {
86
+ source: DeploySource;
87
+ client: ClientFamily;
88
+ };
69
89
  /**
70
90
  * Validate a client-supplied anon id. PostHog device ids are UUID-shaped, so a
71
91
  * conservative charset + length cap is enough to keep anything else (a stray
@@ -3,9 +3,39 @@
3
3
  * two modules importing each other. Nothing else about them changed, and
4
4
  * `deploy-pipeline.ts` still re-exports both so existing imports keep working.
5
5
  */
6
+ /** Which of the upload caps a 413 is about. Each names one `UploadLimits` field (or the JSON cap). */
7
+ export type UploadLimitKind = "files" | "total_bytes" | "zip_bytes" | "json_bytes";
8
+ /**
9
+ * What a 413 knows about itself, beyond its prose.
10
+ *
11
+ * Why it exists: in the week of 2026-10-12, 101 deploys were refused as too
12
+ * large and the only record of any of them was `reason: "too_large"`. The route
13
+ * that catches the error turns this into the response's `limit`/`actual`/`fix`
14
+ * and the `deploy_rejected` event's upload shape (src/upload-shape.ts), so the
15
+ * person gets a fix that fits and the report can say what was in the way.
16
+ */
17
+ export interface TooLargeDetail {
18
+ limit: UploadLimitKind;
19
+ /** The cap itself: a file count, or bytes. */
20
+ limit_value: number;
21
+ /**
22
+ * How far the upload went, in the same unit, when that is known. Omitted for
23
+ * a stream cut off before its end, and whenever the only number available
24
+ * would not be over the cap (an archive that declared smaller sizes than it
25
+ * produced): a message that says "9 MB; the limit is 10 MB" helps nobody.
26
+ */
27
+ actual?: number;
28
+ /**
29
+ * Every file's name and size, when the upload was read far enough to know
30
+ * them. Names stay on the server: only the shape built from them is
31
+ * recorded (upload-shape.ts says why).
32
+ */
33
+ sizes?: Record<string, number>;
34
+ }
6
35
  export declare class IngestError extends Error {
7
36
  status: number;
8
- constructor(message: string, status: number);
37
+ detail?: TooLargeDetail | undefined;
38
+ constructor(message: string, status: number, detail?: TooLargeDetail | undefined);
9
39
  }
10
40
  /** A byte count the way a person reads a limit: "50 MB", "12.5 MB", "800 KB". */
11
41
  export declare function formatBytes(n: number): string;
@@ -16,6 +46,16 @@ export declare function formatBytes(n: number): string;
16
46
  * and "upload too large" left a person guessing how far over they were.
17
47
  */
18
48
  export declare function zipTooLarge(actual: number | null, limit: number): IngestError;
49
+ /** The 413 for a JSON file map over the body cap. Same shape as `zipTooLarge`. */
50
+ export declare function jsonTooLarge(actual: number | null, limit: number): IngestError;
51
+ /**
52
+ * The 413 for an upload whose files are over `maxFiles` or `maxTotalBytes`,
53
+ * once its sizes are known (or as far as they could be).
54
+ *
55
+ * The message names the limit and the number, with no closing period: the CLI
56
+ * quotes it inside its own sentence, as it does `zipTooLarge`'s.
57
+ */
58
+ export declare function filesTooLarge(limit: "files" | "total_bytes", limits: UploadLimits, sizes: Record<string, number> | undefined): IngestError;
19
59
  export interface UploadLimits {
20
60
  maxFiles: number;
21
61
  maxTotalBytes: number;
@@ -0,0 +1,52 @@
1
+ /** The kinds a byte can belong to. Fixed: each becomes a `kb_<kind>` property. */
2
+ export declare const BYTE_KINDS: readonly ["html", "script", "style", "image", "media", "font", "source_map", "data", "archive", "other"];
3
+ export type ByteKind = (typeof BYTE_KINDS)[number];
4
+ /** The kind of one path, by extension. A `.js.map` is a source map, not a script. */
5
+ export declare function kindOf(path: string): ByteKind;
6
+ export interface UploadShape {
7
+ file_count: number;
8
+ total_kb: number;
9
+ /** Kilobytes per kind, only the kinds present. */
10
+ kb_by_kind: Partial<Record<ByteKind, number>>;
11
+ /** The kind holding the most bytes. */
12
+ largest_kind: ByteKind | null;
13
+ /** The kind of the single largest file, and its size. */
14
+ largest_file_kind: ByteKind | null;
15
+ largest_file_kb: number;
16
+ }
17
+ export declare function uploadShape(files: Record<string, Uint8Array>): UploadShape;
18
+ /** Build-output folders a project root usually contains. A fixed list: each is a word, never a path. */
19
+ export declare const BUILD_DIRS: readonly ["dist", "build", "out", "public", "_site", ".output", ".next", "www"];
20
+ /**
21
+ * What the top of an upload says about where it came from. Booleans and words
22
+ * from fixed lists only, for the same reason the shape carries no names.
23
+ *
24
+ * `looks_like_project_root` is the case worth a specific message: a
25
+ * `package.json` and no `index.html` at the top is someone deploying the
26
+ * project instead of its build output, and the fix is one word (`./dist`).
27
+ */
28
+ export interface FolderMarkers {
29
+ has_package_json: boolean;
30
+ has_index_html: boolean;
31
+ has_src_dir: boolean;
32
+ build_dirs: string[];
33
+ looks_like_project_root: boolean;
34
+ }
35
+ export declare function folderMarkers(paths: string[]): FolderMarkers;
36
+ /**
37
+ * Flat analytics properties for a shape and its markers: `file_count`,
38
+ * `total_kb`, `kb_<kind>` for each kind present, `largest_kind`, and the
39
+ * markers. Flat because a HogQL query reads `properties.kb_source_map`, and a
40
+ * nested object would have to be unpacked in every query.
41
+ */
42
+ export declare function shapeProps(shape: UploadShape, markers?: FolderMarkers): Record<string, unknown>;
43
+ /**
44
+ * The one specific sentence that gets an over-limit upload deployed, or null
45
+ * when nothing more specific than "make it smaller" is true.
46
+ *
47
+ * Ordered by how often each is the whole answer: a project root instead of its
48
+ * build folder, then source maps (often half a modern build and never needed to
49
+ * serve it), then video or audio (over any static-host budget on its own), then
50
+ * archives that were never meant to be served.
51
+ */
52
+ export declare function sizeAdvice(shape: UploadShape, markers?: FolderMarkers): string | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flypod",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Zero-auth deploy primitive. Turns any folder into a live URL in one command. For AI agents and humans.",
5
5
  "module": "./dist/src/cli.js",
6
6
  "types": "./dist/src/cli.d.ts",
@@ -14,6 +14,9 @@
14
14
  },
15
15
  "./package.json": "./package.json"
16
16
  },
17
+ "engines": {
18
+ "node": ">=18"
19
+ },
17
20
  "bin": {
18
21
  "flypod": "dist/bin/deploy.js"
19
22
  },
@@ -55,7 +58,7 @@
55
58
  "hono": "^4.13.13",
56
59
  "marked": "^18.1.1",
57
60
  "playwright": "^1.64.1",
58
- "typescript": "^6.0.3",
61
+ "typescript": "^7.0.2",
59
62
  "wrangler": "^4.151.0"
60
63
  }
61
64
  }