@alzulejos/laranja-core 0.2.4

package/dist/api.d.ts

@@ -0,0 +1,274 @@
+/**
+ * The wire contract between the laranja CLI and the laranja server.
+ *
+ * This module is TYPES ONLY (plus a couple of constants) — no runtime logic — so
+ * it can be shared verbatim by the CLI and the backend and keep them in lockstep.
+ *
+ * Auth: every request carries the user's API key in an `x-api-key: <API_KEY>`
+ * header. Project-scoped calls (e.g. `/synth`) also send the dashboard project
+ * id in an `x-project-id: <projectId>` header. Neither is part of any body type
+ * below — identity/context lives in headers, synth inputs in the body.
+ *
+ * Only the Infra IR crosses the wire — never the user's source code.
+ */
+import type { InfraIR } from "./ir.js";
+export declare const API_VERSION = "v1";
+/** Server mounts every route under this prefix (NestJS global prefix + version). */
+export declare const API_PREFIX = "/api/v1";
+/**
+ * Shared endpoint paths, so both sides reference the same strings.
+ *
+ * Deployment reporting is a lifecycle, not a single call: `/synth` opens a
+ * deployment row (`INITIATED`), then the client PATCHes status as it deploys
+ * (`STARTED` → `SUCCESS`/`FAILED`) and POSTs the resource inventory on success.
+ * The `:id` here is the `deploymentId` returned by `/synth`.
+ */
+export declare const ENDPOINTS: {
+    /** GET — verify the API key + return the user and their projects (used by `laranja init`). */
+    readonly me: "/api/v1/me";
+    /** POST — create a project (name only); returns the new project. Used by `laranja init`. */
+    readonly project: "/api/v1/project";
+    /** POST — IR in, CloudFormation template (or CDK files) out; opens the deployment row. */
+    readonly synth: "/api/v1/synth";
+    /** PATCH — advance a deployment's status (STARTED before AWS, then SUCCESS/FAILED). */
+    readonly deployment: (id: string) => string;
+    /** POST — report the deployed resource inventory (success only). */
+    readonly deploymentResources: (id: string) => string;
+    /** POST — open a teardown deployment row (destroy has no `/synth`). */
+    readonly deploymentDestroy: "/api/v1/deployment/destory";
+    /** POST — read-only synth (returns a template, creates NO deployment row). */
+    readonly diff: "/api/v1/diff";
+    /** POST — generate a standalone, owned CDK project (paid; server-gated). */
+    readonly eject: "/api/v1/eject";
+    /** POST — a CLI failure report (free-form), scoped to the user + project. */
+    readonly report: "/api/v1/report";
+};
+export type Tier = "free" | "pro" | "max";
+/** What a tier is allowed to do. `-1` means unlimited. */
+export interface Limits {
+    maxProjects: number;
+    deploysPerDay: number;
+    /** Whether `artifact: "cdk"` (eject) is permitted. */
+    canEject: boolean;
+}
+/** Response from `GET /v1/me` — lets `laranja init` validate the key + greet the user. */
+export interface MeResponse {
+    userId: string;
+    displayName: string;
+    projects: ProjectGroups;
+}
+/** Projects grouped by ownership, mirroring the dashboard's `GET /project`. */
+export interface ProjectGroups {
+    /** Projects the user owns. */
+    personal: Project[];
+    /** Projects shared with the user by someone else. */
+    collaborating: Project[];
+}
+export interface Project {
+    id: string;
+    name: string;
+    /** Detected framework (e.g. "express"); null until a deploy reveals it. */
+    framework: string | null;
+}
+/** `POST /v1/project` body — create a project from the CLI (`laranja init`). */
+export interface CreateProjectRequest {
+    name: string;
+}
+/** `POST /v1/project` response — the new project's id (write it to config). */
+export interface CreateProjectResponse {
+    id: string;
+}
+/** The artifact the client wants from `/synth`. `cdk` requires a paid tier. */
+export type SynthArtifact = "cloudformation" | "cdk";
+/**
+ * Per-handler content hash of the client-built zip, keyed by handler id
+ * ("http" | cron.id | queue.id). The hash is CDK's own `Asset.assetHash`
+ * (a SOURCE fingerprint), computed client-side at bundle time. The server
+ * embeds it into the template as the bootstrap-bucket object key (`<hash>.zip`)
+ * so the Lambda code reference lines up with where the client's toolkit later
+ * uploads the matching zip. Only the hash crosses the wire — never the code.
+ */
+export type HandlerAssetHashes = Record<string, string>;
+/**
+ * What `/synth` reports back per handler so the client can publish its zip to
+ * the exact key the template references.
+ */
+export interface HandlerAsset {
+    /** Handler id — matches the client's bundled-zip id ("http" | cron.id | queue.id). */
+    id: string;
+    /** Short label (e.g. "app", or the cron/queue method name). */
+    label: string;
+    /** Content hash supplied for this handler. */
+    hash: string;
+    /** S3 object key the template references (in the bootstrap assets bucket). */
+    s3Key: string;
+}
+/** `POST /v1/synth` body. */
+export interface SynthRequest {
+    /** Project name/slug — scopes deployments + limit accounting on the server. */
+    project: string;
+    /** Deployment stage, e.g. "dev" / "prod". */
+    stage: string;
+    /** Which artifact to generate. */
+    artifact: SynthArtifact;
+    /** The Infra IR — structure only (routes, crons, queues, env, names). */
+    ir: InfraIR;
+    /** Content hash per handler id, so the template's S3 keys match the client's uploads. */
+    assets: HandlerAssetHashes;
+}
+/** A single generated file (used by the `cdk` artifact). */
+export interface GeneratedFile {
+    /** Path relative to the output dir, e.g. "lib/my-app-stack.ts". */
+    path: string;
+    contents: string;
+}
+interface SynthResponseBase {
+    /** Opaque id linking this synth to the dashboard timeline; echo it to `/deployments`. */
+    deploymentId: string;
+}
+/** Free + paid: the synthesized CloudFormation template the CLI then deploys. */
+export interface CloudFormationSynthResponse extends SynthResponseBase {
+    artifact: "cloudformation";
+    stackName: string;
+    /** CloudFormation template as JSON. */
+    template: Record<string, unknown>;
+    /** Per-handler asset map (hash → S3 key) the client uploads its zips against. */
+    assets: HandlerAsset[];
+}
+/** Paid only: a standalone, editable CDK project (server-side eject). */
+export interface CdkSynthResponse extends SynthResponseBase {
+    artifact: "cdk";
+    files: GeneratedFile[];
+}
+/**
+ * `200` response from `/eject` — the generated standalone CDK project. Like the
+ * `cdk` synth response but with NO `deploymentId` (nothing is persisted). The
+ * server gates this on the caller's `canEject` entitlement (403 otherwise).
+ */
+export interface EjectResponse {
+    files: GeneratedFile[];
+}
+/** `200` response from `/synth` — discriminated on `artifact`. */
+export type SynthResponse = CloudFormationSynthResponse | CdkSynthResponse;
+/**
+ * `200` response from `/diff` — a read-only synth. Same fields as the
+ * CloudFormation synth response but with NO `deploymentId` (nothing is
+ * persisted). Fields are optional to mirror the server's `Partial<SynthResponse>`.
+ */
+export type DiffResponse = Partial<Pick<CloudFormationSynthResponse, "stackName" | "template" | "assets">>;
+/**
+ * A deployment moves through these states. The SERVER owns `INITIATED` (set when
+ * `/synth` opens the row); the CLIENT drives the rest via PATCH. Anything stuck
+ * in `INITIATED`/`STARTED` past a TTL is treated as abandoned by the server.
+ */
+export type DeploymentStatus = "INITIATED" | "STARTED" | "SUCCESS" | "FAILED";
+/**
+ * `PATCH /v1/deployment/:id` body sent right after `/synth`, BEFORE touching AWS.
+ * `region` travels ONLY on this transition (it's where the deploy will land).
+ */
+export interface DeploymentStartedPatch {
+    status: "STARTED";
+    region: string;
+}
+/**
+ * `PATCH /v1/deployment/:id` body sent after the AWS deploy settles. No region.
+ * The success handler must be idempotent (a retried PATCH must not error).
+ */
+export interface DeploymentOutcomePatch {
+    status: "SUCCESS" | "FAILED";
+}
+/** Every client-driven status PATCH body, discriminated on `status`. */
+export type DeploymentPatch = DeploymentStartedPatch | DeploymentOutcomePatch;
+/**
+ * Logical resource kind, for dashboard grouping/icons. ("function" = a plain
+ * compute fn — provider-neutral.) For an `http` proxy the logical name is "http".
+ */
+export type DeployedResourceType = "http" | "cron" | "queue" | "function" | "dashboard";
+/**
+ * How a resource changed in this deploy, derived from the CloudFormation change
+ * set (Add → CREATED, Modify → UPDATED, Remove → REMOVED). Computed against live
+ * AWS state so reports self-heal if one is ever missed.
+ */
+export type DeployedResourceAction = "CREATED" | "REMOVED" | "UPDATED";
+/**
+ * Free-form, kind-specific config bag stored on each resource (BE column is
+ * jsonb). Open by design — extra keys are allowed — but two are conventional:
+ * `warnings` for non-fatal per-resource issues (env names only, no values).
+ */
+export interface ResourceMetadata {
+    /** Non-fatal issues affecting this resource — e.g. unpopulated env-var NAMES. */
+    warnings?: string[];
+    [key: string]: unknown;
+}
+/**
+ * One LOGICAL laranja resource (not one physical AWS resource) in the deployed
+ * inventory, reported so the dashboard can show an inventory + deep-link to the
+ * console.
+ *
+ * SECURITY: identifiers ONLY — never env-var values or secrets. ARNs/URLs are
+ * not credentials, but treat this as tenant-scoped data (per-user authz on read).
+ */
+export interface DeployedResource {
+    /** Logical id, e.g. "cleanup", "process-order", or "http" for the proxy. */
+    name: string;
+    type: DeployedResourceType;
+    action: DeployedResourceAction;
+    /**
+     * Kind-specific config (cron schedule, queue name/fifo/batchSize, lambda cfg).
+     * MUST be `{}` when there's nothing to report — never `null`. No routes.
+     *
+     * May also carry `warnings: string[]` — non-fatal issues affecting THIS
+     * resource, e.g. the NAMES of env vars that had no value at deploy time. Names
+     * only, never values/secrets. (BE stores `metadata` as jsonb, so no schema
+     * change is needed to add this.)
+     */
+    metadata: ResourceMetadata;
+    /** Primary Lambda function ARN. `null` for REMOVED if unknown. */
+    externalId: string | null;
+    /** For `http`, the Lambda Function URL (no API Gateway). `null` for cron/queue. */
+    externalUrl: string | null;
+}
+/**
+ * `POST /v1/deployment/:id/resources` body — the deployed inventory, sent on
+ * SUCCESS only. WRAPPED in an object (a bare array 500s the BE controller).
+ */
+export interface ResourcesReport {
+    resources: DeployedResource[];
+}
+/**
+ * `POST /v1/deployment/destory` body — opens a teardown deployment row. A destroy
+ * never hits `/synth` (nothing to synthesize), so this is how it gets a row + id.
+ * The project comes from the API key; the body identifies the stack being torn
+ * down. The BE owns the REMOVED resource inventory (from the last deployment).
+ */
+export interface DestroyRequest {
+    /** Physical stack name, e.g. "myapp-dev". */
+    stackName: string;
+    artifact: SynthArtifact;
+    /** Target cloud, e.g. "AWS". */
+    provider: string;
+    region: string;
+}
+/** `POST /v1/deployment/destory` response — the new teardown row's id. */
+export interface DestroyResponse {
+    deploymentId: string;
+}
+/**
+ * Error codes returned in the body alongside a non-2xx status:
+ *   unauthorized   -> 401   (missing/invalid API key)
+ *   project_access -> 403   (valid key, but no access to the requested project)
+ *   forbidden      -> 403   (valid key, not entitled — e.g. cdk on free)
+ *   limit_exceeded -> 402   (deploys/day or project cap hit)
+ *   invalid_request-> 400   (malformed IR / payload)
+ *   server_error   -> 500
+ */
+export type ApiErrorCode = "unauthorized" | "project_access" | "forbidden" | "limit_exceeded" | "invalid_request" | "server_error";
+export interface ApiError {
+    error: ApiErrorCode;
+    message: string;
+    /** Where to upgrade, when relevant (limit_exceeded / forbidden). */
+    upgradeUrl?: string;
+    /** For rate limits: seconds until the client may retry. */
+    retryAfter?: number;
+}
+export {};

package/dist/api.js

@@ -0,0 +1,45 @@
+/**
+ * The wire contract between the laranja CLI and the laranja server.
+ *
+ * This module is TYPES ONLY (plus a couple of constants) — no runtime logic — so
+ * it can be shared verbatim by the CLI and the backend and keep them in lockstep.
+ *
+ * Auth: every request carries the user's API key in an `x-api-key: <API_KEY>`
+ * header. Project-scoped calls (e.g. `/synth`) also send the dashboard project
+ * id in an `x-project-id: <projectId>` header. Neither is part of any body type
+ * below — identity/context lives in headers, synth inputs in the body.
+ *
+ * Only the Infra IR crosses the wire — never the user's source code.
+ */
+export const API_VERSION = "v1";
+/** Server mounts every route under this prefix (NestJS global prefix + version). */
+export const API_PREFIX = `/api/${API_VERSION}`;
+/**
+ * Shared endpoint paths, so both sides reference the same strings.
+ *
+ * Deployment reporting is a lifecycle, not a single call: `/synth` opens a
+ * deployment row (`INITIATED`), then the client PATCHes status as it deploys
+ * (`STARTED` → `SUCCESS`/`FAILED`) and POSTs the resource inventory on success.
+ * The `:id` here is the `deploymentId` returned by `/synth`.
+ */
+export const ENDPOINTS = {
+    /** GET — verify the API key + return the user and their projects (used by `laranja init`). */
+    me: `${API_PREFIX}/me`,
+    /** POST — create a project (name only); returns the new project. Used by `laranja init`. */
+    project: `${API_PREFIX}/project`,
+    /** POST — IR in, CloudFormation template (or CDK files) out; opens the deployment row. */
+    synth: `${API_PREFIX}/synth`,
+    /** PATCH — advance a deployment's status (STARTED before AWS, then SUCCESS/FAILED). */
+    deployment: (id) => `${API_PREFIX}/deployment/${id}`,
+    /** POST — report the deployed resource inventory (success only). */
+    deploymentResources: (id) => `${API_PREFIX}/deployment/${id}/resources`,
+    /** POST — open a teardown deployment row (destroy has no `/synth`). */
+    deploymentDestroy: `${API_PREFIX}/deployment/destory`,
+    /** POST — read-only synth (returns a template, creates NO deployment row). */
+    diff: `${API_PREFIX}/diff`,
+    /** POST — generate a standalone, owned CDK project (paid; server-gated). */
+    eject: `${API_PREFIX}/eject`,
+    /** POST — a CLI failure report (free-form), scoped to the user + project. */
+    report: `${API_PREFIX}/report`,
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC;AAEhC,oFAAoF;AACpF,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,WAAW,EAAE,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,8FAA8F;IAC9F,EAAE,EAAE,GAAG,UAAU,KAAK;IACtB,4FAA4F;IAC5F,OAAO,EAAE,GAAG,UAAU,UAAU;IAChC,0FAA0F;IAC1F,KAAK,EAAE,GAAG,UAAU,QAAQ;IAC5B,uFAAuF;IACvF,UAAU,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,GAAG,UAAU,eAAe,EAAE,EAAE;IAC5D,oEAAoE;IACpE,mBAAmB,EAAE,CAAC,EAAU,EAAE,EAAE,CAClC,GAAG,UAAU,eAAe,EAAE,YAAY;IAC5C,uEAAuE;IACvE,iBAAiB,EAAE,GAAG,UAAU,qBAAqB;IACrD,8EAA8E;IAC9E,IAAI,EAAE,GAAG,UAAU,OAAO;IAC1B,4EAA4E;IAC5E,KAAK,EAAE,GAAG,UAAU,QAAQ;IAC5B,6EAA6E;IAC7E,MAAM,EAAE,GAAG,UAAU,SAAS;CACtB,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Global, user-level credential store for the laranja CLI.
+ *
+ * The API key is account-scoped (the same key works for every project), so it
+ * lives once in the user's home dir — NOT in the committed `laranja.config.ts`.
+ * This is the Vercel-style "log in once" model: `laranja init` validates the
+ * key against `/me` and then persists it here, so later commands don't need
+ * `LARANJA_API_KEY` re-exported in every shell.
+ *
+ * Layout (cross-platform via `os.homedir()`):
+ *   ~/.laranja/auth.json        (file mode 0600, dir mode 0700 where supported)
+ *   { "apiKey": "...", "apiUrl": "..." }
+ */
+/** Directory holding laranja's user-level state. Override with `LARANJA_HOME`. */
+export declare function authDir(): string;
+/** Path to the credential file. */
+export declare function authFilePath(): string;
+/** On-disk shape of the credential file. */
+export interface StoredAuth {
+    apiKey: string;
+    /** The API URL the key was validated against — informational. */
+    apiUrl?: string;
+}
+/** Read the stored credentials, or `undefined` if none / unreadable. */
+export declare function loadStoredAuth(): StoredAuth | undefined;
+/** Convenience: just the stored key, if any. */
+export declare function loadStoredApiKey(): string | undefined;
+/**
+ * Persist credentials to `~/.laranja/auth.json` with owner-only permissions.
+ * Creates the directory if needed. Returns the path written.
+ */
+export declare function storeAuth(auth: StoredAuth): string;
+/**
+ * Delete the stored credentials (`laranja logout`). Returns `true` if a file
+ * was removed, `false` if there was nothing stored.
+ */
+export declare function clearAuth(): boolean;

package/dist/auth.js

@@ -0,0 +1,78 @@
+/**
+ * Global, user-level credential store for the laranja CLI.
+ *
+ * The API key is account-scoped (the same key works for every project), so it
+ * lives once in the user's home dir — NOT in the committed `laranja.config.ts`.
+ * This is the Vercel-style "log in once" model: `laranja init` validates the
+ * key against `/me` and then persists it here, so later commands don't need
+ * `LARANJA_API_KEY` re-exported in every shell.
+ *
+ * Layout (cross-platform via `os.homedir()`):
+ *   ~/.laranja/auth.json        (file mode 0600, dir mode 0700 where supported)
+ *   { "apiKey": "...", "apiUrl": "..." }
+ */
+import os from "node:os";
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+/** Directory holding laranja's user-level state. Override with `LARANJA_HOME`. */
+export function authDir() {
+    return process.env.LARANJA_HOME?.trim() || path.join(os.homedir(), ".laranja");
+}
+/** Path to the credential file. */
+export function authFilePath() {
+    return path.join(authDir(), "auth.json");
+}
+/** Read the stored credentials, or `undefined` if none / unreadable. */
+export function loadStoredAuth() {
+    const file = authFilePath();
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const data = JSON.parse(readFileSync(file, "utf8"));
+        const apiKey = data.apiKey?.trim();
+        if (!apiKey)
+            return undefined;
+        return { apiKey, apiUrl: data.apiUrl };
+    }
+    catch {
+        // Corrupt file — treat as "not logged in" rather than crashing the CLI.
+        return undefined;
+    }
+}
+/** Convenience: just the stored key, if any. */
+export function loadStoredApiKey() {
+    return loadStoredAuth()?.apiKey;
+}
+/**
+ * Persist credentials to `~/.laranja/auth.json` with owner-only permissions.
+ * Creates the directory if needed. Returns the path written.
+ */
+export function storeAuth(auth) {
+    const dir = authDir();
+    // `recursive: true` makes mkdir a no-op if the dir already exists.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = authFilePath();
+    writeFileSync(file, JSON.stringify(auth, null, 2) + "\n", { mode: 0o600 });
+    // mkdir/writeFile honor `mode` only on creation; enforce it explicitly so an
+    // existing, looser file is tightened. (On Windows chmod is a best-effort
+    // no-op — POSIX perms don't apply there; the file lives in the user profile.)
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best-effort on platforms without POSIX permissions */
+    }
+    return file;
+}
+/**
+ * Delete the stored credentials (`laranja logout`). Returns `true` if a file
+ * was removed, `false` if there was nothing stored.
+ */
+export function clearAuth() {
+    const file = authFilePath();
+    if (!existsSync(file))
+        return false;
+    rmSync(file, { force: true });
+    return true;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEhG,kFAAkF;AAClF,MAAM,UAAU,OAAO;IACrB,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AACjF,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC3C,CAAC;AASD,wEAAwE;AACxE,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAwB,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,EAAE,EAAE,MAAM,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,mEAAmE;IACnE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,8EAA8E;IAC9E,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The laranja API client — the CLI's side of the wire contract in `api.ts`.
+ *
+ * Zero-dep: uses the global `fetch` (Node 18+). Only the Infra IR ever crosses
+ * the wire (see `SynthRequest`); the user's source code never leaves the machine.
+ */
+import { type MeResponse, type CreateProjectResponse, type SynthRequest, type SynthResponse, type DiffResponse, type EjectResponse, type DeploymentPatch, type ResourcesReport, type DestroyRequest, type ApiErrorCode } from "./api.js";
+/** Default server URL for local development. Override with `LARANJA_API_URL`. */
+export declare const DEFAULT_API_URL = "https://api.laranja.io";
+/** Where to reach the server. Env override lets us point at prod later. */
+export declare function resolveApiUrl(): string;
+/**
+ * The caller's API key. Precedence: `LARANJA_API_KEY` env var (CI / one-off
+ * override) wins, then the key persisted by `laranja init` (~/.laranja/auth.json).
+ * The env override means a stored login never blocks a different key in CI.
+ */
+export declare function resolveApiKey(): string | undefined;
+/** A failed API call — carries the server's error code so callers can branch. */
+export declare class ApiRequestError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    readonly upgradeUrl?: string | undefined;
+    constructor(code: ApiErrorCode, message: string, status: number, upgradeUrl?: string | undefined);
+}
+/** Base URL of the laranja dashboard web app. Override with `LARANJA_DASHBOARD_URL` for local dev. */
+export declare const DASHBOARD_URL: string;
+/** Dashboard page where users create / manage their API keys. */
+export declare const DASHBOARD_KEYS_URL: string;
+/**
+ * True when an error means the API key itself is the problem — missing,
+ * expired, or deleted — as opposed to an entitlement issue.
+ *
+ * The server is inconsistent about how it reports a bad key (it leans on
+ * NestJS's generic exceptions rather than our structured `ApiErrorCode`):
+ *   - a proper `401`,
+ *   - a `400 { error: "Bad Request", message: "Invalid API KEY" }`,
+ *   - a `403 { error: "Forbidden", message: "Forbidden resource" }` when an
+ *     expired/deleted key trips the auth guard.
+ * So we treat any 401/403, or a message of "Invalid API KEY", as a bad key.
+ *
+ * The one 403 that is NOT a key problem is a *real* entitlement failure ("valid
+ * key, not entitled"), which uses our structured contract: lower-case `code:
+ * "forbidden"` + an `upgradeUrl`. NestJS's generic guard rejection instead puts
+ * capital-`F` `"Forbidden"` in the body's `error` field, so the two don't
+ * collide — we exclude only the lower-case structured code.
+ */
+export declare function isAuthKeyError(err: unknown): boolean;
+/**
+ * Turn an `ApiRequestError` into a friendly, actionable one-or-many-line
+ * message, prefixed with the failing step (e.g. "Handshake failed"). Bad-key
+ * errors get create-a-new-key guidance; an unreachable server gets a "is it
+ * running?" hint; everything else falls back to the server's own message.
+ */
+export declare function apiErrorMessage(prefix: string, err: ApiRequestError): string;
+/**
+ * `GET /v1/me` — validate the API key and fetch the caller's tier/limits.
+ * Used by `laranja init` to handshake with the server.
+ */
+export declare function getMe(apiKey: string, baseUrl?: string): Promise<MeResponse>;
+/**
+ * `POST /v1/project` — create a project (name only) from the CLI and get back
+ * its server id. User-scoped: authed by the API key, no `x-project-id`.
+ */
+export declare function createProject(name: string, apiKey: string, baseUrl?: string): Promise<CreateProjectResponse>;
+/**
+ * `POST /v1/synth` — send the Infra IR, get back a CloudFormation template
+ * (or, for paid tiers, a CDK project). Only the IR crosses the wire; the
+ * dashboard `projectId` rides in the `x-project-id` header.
+ */
+export declare function postSynth(req: SynthRequest, apiKey: string, projectId: string, baseUrl?: string): Promise<SynthResponse>;
+/**
+ * `POST /v1/diff` — a read-only synth: same input as `/synth`, returns a template
+ * to diff against the deployed stack, but creates NO deployment row.
+ */
+export declare function postDiff(req: SynthRequest, apiKey: string, projectId: string, baseUrl?: string): Promise<DiffResponse>;
+/**
+ * `POST /v1/eject` — generate a standalone, owned CDK project from the IR. The
+ * server gates this on the caller's entitlement (403 if not allowed). Nothing is
+ * persisted; the client writes the returned files to disk.
+ */
+export declare function postEject(req: SynthRequest, apiKey: string, projectId: string, baseUrl?: string): Promise<EjectResponse>;
+/**
+ * `POST /v1/report` — send a free-form CLI failure report, scoped to the user
+ * (api key) + project (project id). Diagnostics only; the body shape is open.
+ */
+export declare function postReport(report: Record<string, unknown>, apiKey: string, projectId: string, baseUrl?: string): Promise<unknown>;
+/**
+ * `PATCH /v1/deployment/:id` — advance a deployment's status. Sent with
+ * `{ status: "STARTED", region }` before touching AWS, then `{ status: "SUCCESS"
+ * | "FAILED" }` once the deploy settles. The dashboard `projectId` rides in the
+ * `x-project-id` header, consistent with the rest of the deploy/destroy calls.
+ */
+export declare function patchDeployment(deploymentId: string, body: DeploymentPatch, apiKey: string, projectId: string, baseUrl?: string): Promise<boolean>;
+/**
+ * `POST /v1/deployment/:id/resources` — report the deployed inventory after a
+ * successful deploy. Body is WRAPPED (`{ resources }`); a bare array 500s the BE.
+ */
+export declare function postDeploymentResources(deploymentId: string, body: ResourcesReport, apiKey: string, projectId: string, baseUrl?: string): Promise<boolean>;
+/**
+ * `POST /v1/deployment/destory` — open a teardown deployment row and get its id,
+ * so a destroy can drive the same status lifecycle (STARTED → SUCCESS/FAILED).
+ * Tolerates either a `{ deploymentId }` body or a bare id string.
+ */
+export declare function postDestroy(req: DestroyRequest, apiKey: string, projectId: string, baseUrl?: string): Promise<string>;