flypod 0.16.1 → 0.18.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.
@@ -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,10 +3,57 @@
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
+ import type { ApiErrorCode } from "./api-error";
7
+ /** Which of the upload caps a 413 is about. Each names one `UploadLimits` field (or the JSON cap). */
8
+ export type UploadLimitKind = "files" | "total_bytes" | "zip_bytes" | "json_bytes";
9
+ /**
10
+ * What a 413 knows about itself, beyond its prose.
11
+ *
12
+ * Why it exists: in the week of 2026-10-12, 101 deploys were refused as too
13
+ * large and the only record of any of them was `reason: "too_large"`. The route
14
+ * that catches the error turns this into the response's `limit`/`actual`/`fix`
15
+ * and the `deploy_rejected` event's upload shape (src/upload-shape.ts), so the
16
+ * person gets a fix that fits and the report can say what was in the way.
17
+ */
18
+ export interface TooLargeDetail {
19
+ limit: UploadLimitKind;
20
+ /** The cap itself: a file count, or bytes. */
21
+ limit_value: number;
22
+ /**
23
+ * How far the upload went, in the same unit, when that is known. Omitted for
24
+ * a stream cut off before its end, and whenever the only number available
25
+ * would not be over the cap (an archive that declared smaller sizes than it
26
+ * produced): a message that says "9 MB; the limit is 10 MB" helps nobody.
27
+ */
28
+ actual?: number;
29
+ /**
30
+ * Every file's name and size, when the upload was read far enough to know
31
+ * them. Names stay on the server: only the shape built from them is
32
+ * recorded (upload-shape.ts says why).
33
+ */
34
+ sizes?: Record<string, number>;
35
+ }
6
36
  export declare class IngestError extends Error {
7
37
  status: number;
8
- constructor(message: string, status: number);
38
+ detail?: TooLargeDetail | undefined;
39
+ /** The API code, when the status alone would name the wrong one. */
40
+ code?: ApiErrorCode | undefined;
41
+ constructor(message: string, status: number, detail?: TooLargeDetail | undefined,
42
+ /** The API code, when the status alone would name the wrong one. */
43
+ code?: ApiErrorCode | undefined);
9
44
  }
45
+ /**
46
+ * The upload stopped arriving: the request body's stream failed partway,
47
+ * which is what a caller that gave up mid-upload (a timeout, a killed agent,
48
+ * a dropped connection) looks like from here.
49
+ *
50
+ * It used to escape as a thrown read error and be answered, and recorded, as
51
+ * a `500 server_error`: our fault, in a week when the report was trying to
52
+ * work out which `server_error`s were. Nobody is left to read the answer; the
53
+ * point is what `deploy_failed` says, so it is a `400 bad_request`, apart
54
+ * from the `invalid_upload` of a body that arrived whole and was wrong.
55
+ */
56
+ export declare function uploadInterrupted(): IngestError;
10
57
  /** A byte count the way a person reads a limit: "50 MB", "12.5 MB", "800 KB". */
11
58
  export declare function formatBytes(n: number): string;
12
59
  /**
@@ -16,6 +63,16 @@ export declare function formatBytes(n: number): string;
16
63
  * and "upload too large" left a person guessing how far over they were.
17
64
  */
18
65
  export declare function zipTooLarge(actual: number | null, limit: number): IngestError;
66
+ /** The 413 for a JSON file map over the body cap. Same shape as `zipTooLarge`. */
67
+ export declare function jsonTooLarge(actual: number | null, limit: number): IngestError;
68
+ /**
69
+ * The 413 for an upload whose files are over `maxFiles` or `maxTotalBytes`,
70
+ * once its sizes are known (or as far as they could be).
71
+ *
72
+ * The message names the limit and the number, with no closing period: the CLI
73
+ * quotes it inside its own sentence, as it does `zipTooLarge`'s.
74
+ */
75
+ export declare function filesTooLarge(limit: "files" | "total_bytes", limits: UploadLimits, sizes: Record<string, number> | undefined): IngestError;
19
76
  export interface UploadLimits {
20
77
  maxFiles: number;
21
78
  maxTotalBytes: number;
@@ -0,0 +1,57 @@
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;
53
+ /**
54
+ * Which of `sizeAdvice`'s answers applies, as a word: the CLI uses it to pick
55
+ * which files to name (it has the names; the server and the report do not).
56
+ */
57
+ export declare function sizeCause(shape: UploadShape, markers?: FolderMarkers): "project_root" | "source_map" | "media" | "archive" | "image" | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flypod",
3
- "version": "0.16.1",
3
+ "version": "0.18.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
  },