creat01deployengine 1.0.0

package/AI_USAGE.md

@@ -0,0 +1,62 @@
+# AI usage guide — TypeScript
+
+Use this decision order when generating code with `creat01deployengine`.
+
+1. Use `DeployEngineClient` only in trusted Node.js/server code and read the
+   management API key from `DEPLOYENGINE_API_KEY` in the environment.
+2. Browser code may import `creat01deployengine/tracking` and
+   `creat01deployengine/logging` with a project-scoped `writeKey` only.
+3. Prefer `client.api.<resource>` methods over `client.request`.
+4. Do not retry writes unless an idempotency key is provided.
+5. Catch typed errors and retain `requestId` for support diagnostics.
+
+## Method selection
+
+```text
+resource CRUD                  -> list/get/create/update/delete
+deployment history            -> api.projects.deployments
+release history               -> api.projects.releases
+deployment validation         -> api.projects.precheck
+deploy/restart with progress  -> api.projects.deployStream/restartStream
+machine recommendation/state  -> api.machines.recommendations/agentStatus
+workflow task CRUD             -> api.workflows.list/get/create/update/delete
+certificate CRUD               -> api.certificates.list/get/create/update/delete
+domain CRUD                    -> api.domains.list/get/create/update/delete
+alert-contact CRUD             -> api.alerts.list/get/create/update/delete
+load-balancer update/sync     -> api.loadBalancers.update/sync
+bind project to load balancer -> api.loadBalancers.bindProject
+firewall update/apply/rule    -> api.securityGroups.update/apply/addRule
+payment/refund                -> api.payments.createOrder/refund
+send/login with code          -> api.authentication.sendCode/loginWithCode
+password login                -> api.authentication.passwordLogin
+feedback link                 -> api.feedback.createTicketLink
+event batch                   -> api.tracking.collect
+browser analytics             -> Tracker.track/identify/flush/close
+browser-safe logs             -> LogReporter.debug/info/warn/error
+```
+
+```ts
+import {
+  DeployEngineClient,
+  DeployEngineError,
+} from "creat01deployengine"
+
+const client = new DeployEngineClient({
+  apiKey: process.env.DEPLOYENGINE_API_KEY,
+})
+
+try {
+  for await (const event of client.api.projects.deployStream(projectId, body)) {
+    console.log(event)
+  }
+} catch (error) {
+  if (error instanceof DeployEngineError) {
+    console.error(error.statusCode, error.code, error.requestId)
+  }
+  throw error
+}
+```
+
+Scopes: `read`, `deploy`, `machines`, `databases`, `certificates`,
+`monitoring`, `infrastructure`, and `business`. A 403 is an authorization
+problem; do not expose or silently replace the credential.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Creat01
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# creat01deployengine TypeScript SDK
+
+Official ESM client for Node.js 18+ and modern browsers.
+
+```bash
+npm install creat01deployengine
+```
+
+## Management API (trusted servers only)
+
+```ts
+import { DeployEngineClient } from "creat01deployengine"
+
+const client = new DeployEngineClient({
+  apiKey: process.env.DEPLOYENGINE_API_KEY,
+  baseUrl: "https://deployengine.creat01.com",
+})
+const projects = await client.api.projects.list({ page: 1, pageSize: 20 })
+await client.api.securityGroups.apply(12)
+```
+
+Never include a management `apiKey` or bearer `accessToken` in browser,
+desktop, or mobile bundles.
+
+## Browser-safe tracking and logging
+
+```ts
+import { Tracker } from "creat01deployengine/tracking"
+import { LogReporter } from "creat01deployengine/logging"
+
+const tracker = new Tracker({
+  baseUrl: "https://deployengine.creat01.com",
+  appId: "app_xxx",
+  projectName: "shop",
+  writeKey: "wk_xxx",
+})
+tracker.track("checkout_started", { sku: "A-1" }, "user-1")
+new LogReporter(tracker, { service: "web", environment: "production" })
+  .error("render failed", { traceId: "trace-1" })
+await tracker.close()
+```
+
+## Resource map
+
+| `client.api` member | Purpose | Typical scope |
+|---|---|---|
+| `projects` | CRUD, precheck, deployments, releases, streams | `read`, `deploy` |
+| `machines` | CRUD, recommendations, Agent status | `machines` |
+| `workflows` | Generic workflow task CRUD access | `read`, `deploy` |
+| `certificates` | Generic certificate CRUD access | `certificates` |
+| `domains` | Generic domain CRUD access | `read` |
+| `loadBalancers` | Update, remote sync, project binding | `infrastructure` |
+| `securityGroups` | Update, apply, add firewall rule | `infrastructure` |
+| `alerts` | Generic alert-contact CRUD access | `monitoring` |
+| `payments` | Create orders and refunds | `business` |
+| `authentication` | Project SMS/email/password login | `business` |
+| `feedback` | Customer feedback links | `business` |
+| `tracking` | Low-level event ingestion | tracking write key |
+
+```ts
+for await (const event of client.api.projects.deployStream(7, body)) {
+  console.log(event)
+}
+```
+
+Responses are unwrapped and failures become typed errors. Reads can retry;
+writes retry only with an idempotency key. See `AI_USAGE.md` for task recipes.

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+/** Configuration for an authenticated DeployEngine management client. */
+export interface ClientOptions {
+    /** Secret management API key. Never include this in browser bundles. */
+    apiKey?: string;
+    /** Bearer access token used when an API key is unavailable. */
+    accessToken?: string;
+    /** DeployEngine origin, without a required trailing slash. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Safe retry count for reads or idempotent writes. Defaults to two. */
+    maxRetries?: number;
+    /** Custom Fetch implementation, primarily for runtimes and tests. */
+    fetch?: typeof fetch;
+}
+type RequestOptions = {
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+};
+/**
+ * Low-level authenticated management client.
+ * Use `DeployEngineClient` for the convenient `api` resource registry.
+ */
+export declare class DeployEngine {
+    /** Normalized DeployEngine origin used for every request. */
+    readonly baseUrl: string;
+    private auth;
+    private timeoutMs;
+    private maxRetries;
+    private fetcher;
+    constructor(options: ClientOptions);
+    /**
+     * Send an API request and return the unwrapped `data` field.
+     *
+     * GET/HEAD requests may retry automatically. Writes retry only when
+     * `idempotencyKey` is present. API failures become typed SDK errors.
+     * Prefer a domain resource such as `client.api.projects` in application code.
+     */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private delay;
+    /**
+     * Stream decoded Server-Sent Event `data:` payloads.
+     *
+     * JSON payloads are returned as `T`; plain-text payloads remain strings.
+     * Consuming a stream may start a side-effecting deployment or restart.
+     */
+    stream<T = unknown>(method: string, path: string, body?: unknown): AsyncGenerator<T | string>;
+}
+export {};
+/** Authenticated transport used by all DeployEngine management resources. */

package/dist/client.js

@@ -0,0 +1,161 @@
+import { AuthenticationError, ConflictError, DeployEngineError, NotFoundError, PermissionDeniedError, RateLimitError, ValidationError, } from "./errors.js";
+import { VERSION } from "./version.js";
+const errors = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+};
+const retryable = new Set([429, 502, 503, 504]);
+/**
+ * Low-level authenticated management client.
+ * Use `DeployEngineClient` for the convenient `api` resource registry.
+ */
+export class DeployEngine {
+    /** Normalized DeployEngine origin used for every request. */
+    baseUrl;
+    auth;
+    timeoutMs;
+    maxRetries;
+    fetcher;
+    constructor(options) {
+        if (!options.apiKey && !options.accessToken)
+            throw new TypeError("apiKey or accessToken is required");
+        this.baseUrl = (options.baseUrl ?? "https://deployengine.creat01.com").replace(/\/$/, "");
+        this.auth = options.apiKey
+            ? { "X-API-KEY": options.apiKey }
+            : { Authorization: `Bearer ${options.accessToken}` };
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = Math.max(0, options.maxRetries ?? 2);
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    /**
+     * Send an API request and return the unwrapped `data` field.
+     *
+     * GET/HEAD requests may retry automatically. Writes retry only when
+     * `idempotencyKey` is present. API failures become typed SDK errors.
+     * Prefer a domain resource such as `client.api.projects` in application code.
+     */
+    async request(method, path, options = {}) {
+        const url = new URL(path, `${this.baseUrl}/`);
+        for (const [key, value] of Object.entries(options.query ?? {}))
+            if (value !== undefined && value !== null)
+                url.searchParams.set(key, String(value));
+        const headers = {
+            ...this.auth,
+            "User-Agent": `creat01deployengine-typescript/${VERSION}`,
+            "X-DeployEngine-SDK-Version": VERSION,
+            "X-Request-ID": crypto.randomUUID(),
+            ...options.headers,
+        };
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (options.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        const canRetry = ["GET", "HEAD"].includes(method.toUpperCase()) ||
+            Boolean(options.idempotencyKey);
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const response = await this.fetcher(url, {
+                    method,
+                    headers,
+                    body: options.body === undefined
+                        ? undefined
+                        : JSON.stringify(options.body),
+                    signal: options.signal ?? controller.signal,
+                });
+                const raw = await response.text();
+                let payload = {};
+                try {
+                    payload = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    payload = {};
+                }
+                const bodyStatus = Number(payload?.status_code ?? response.status);
+                if (response.ok && bodyStatus < 400)
+                    return (payload && Object.hasOwn(payload, "data") ? payload.data : payload);
+                if (canRetry &&
+                    retryable.has(response.status) &&
+                    attempt < this.maxRetries) {
+                    await this.delay(attempt, response.headers.get("Retry-After"));
+                    continue;
+                }
+                const ErrorType = errors[response.status] ?? DeployEngineError;
+                throw new ErrorType(payload?.detail ??
+                    payload?.message ??
+                    raw.slice(0, 500) ??
+                    "DeployEngine request failed", response.status, payload?.code, response.headers.get("X-Request-ID") ?? undefined, payload?.data, retryable.has(response.status));
+            }
+            catch (error) {
+                if (error instanceof DeployEngineError ||
+                    !canRetry ||
+                    attempt >= this.maxRetries)
+                    throw error;
+                await this.delay(attempt);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+    }
+    delay(attempt, retryAfter) {
+        const seconds = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) : 0;
+        return new Promise((resolve) => setTimeout(resolve, seconds ? seconds * 1000 : 250 * 2 ** attempt + Math.random() * 100));
+    }
+    /**
+     * Stream decoded Server-Sent Event `data:` payloads.
+     *
+     * JSON payloads are returned as `T`; plain-text payloads remain strings.
+     * Consuming a stream may start a side-effecting deployment or restart.
+     */
+    async *stream(method, path, body) {
+        const headers = {
+            ...this.auth,
+            Accept: "text/event-stream",
+            "X-Request-ID": crypto.randomUUID(),
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const response = await this.fetcher(new URL(path, `${this.baseUrl}/`), {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!response.ok || !response.body)
+            throw new DeployEngineError(`Stream request failed (${response.status})`, response.status);
+        const reader = response.body
+            .pipeThrough(new TextDecoderStream())
+            .getReader();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += value;
+                const lines = buffer.split(/\r?\n/);
+                buffer = lines.pop() ?? "";
+                for (const line of lines)
+                    if (line.startsWith("data:")) {
+                        const data = line.slice(5).trim();
+                        try {
+                            yield JSON.parse(data);
+                        }
+                        catch {
+                            yield data;
+                        }
+                    }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+/** Authenticated transport used by all DeployEngine management resources. */

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/** Typed errors raised by DeployEngine management requests. */
+export declare class DeployEngineError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    requestId?: string | undefined;
+    details?: unknown | undefined;
+    retryable: boolean;
+    /** Create an error containing server diagnostics and retry metadata. */
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, requestId?: string | undefined, details?: unknown | undefined, retryable?: boolean);
+}
+/** The credential is missing, invalid, or expired (HTTP 401). */
+export declare class AuthenticationError extends DeployEngineError {
+}
+/** The credential lacks the required API scope (HTTP 403). */
+export declare class PermissionDeniedError extends DeployEngineError {
+}
+/** The resource is missing or inaccessible to this account (HTTP 404). */
+export declare class NotFoundError extends DeployEngineError {
+}
+/** The operation conflicts with current resource state (HTTP 409). */
+export declare class ConflictError extends DeployEngineError {
+}
+/** Request fields or query parameters are invalid (HTTP 400/422). */
+export declare class ValidationError extends DeployEngineError {
+}
+/** A server rate limit was exceeded and the operation may be retryable. */
+export declare class RateLimitError extends DeployEngineError {
+}

package/dist/errors.js

@@ -0,0 +1,36 @@
+/** Typed errors raised by DeployEngine management requests. */
+export class DeployEngineError extends Error {
+    statusCode;
+    code;
+    requestId;
+    details;
+    retryable;
+    /** Create an error containing server diagnostics and retry metadata. */
+    constructor(message, statusCode, code, requestId, details, retryable = false) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.requestId = requestId;
+        this.details = details;
+        this.retryable = retryable;
+        this.name = new.target.name;
+    }
+}
+/** The credential is missing, invalid, or expired (HTTP 401). */
+export class AuthenticationError extends DeployEngineError {
+}
+/** The credential lacks the required API scope (HTTP 403). */
+export class PermissionDeniedError extends DeployEngineError {
+}
+/** The resource is missing or inaccessible to this account (HTTP 404). */
+export class NotFoundError extends DeployEngineError {
+}
+/** The operation conflicts with current resource state (HTTP 409). */
+export class ConflictError extends DeployEngineError {
+}
+/** Request fields or query parameters are invalid (HTTP 400/422). */
+export class ValidationError extends DeployEngineError {
+}
+/** A server rate limit was exceeded and the operation may be retryable. */
+export class RateLimitError extends DeployEngineError {
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/** Main package entry point for management, tracking, logging, models, and errors. */
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./resources/index.js";
+export * from "./tracking/index.js";
+export * from "./logging/index.js";
+export * from "./models/index.js";
+export * from "./version.js";
+import { DeployEngine, type ClientOptions } from "./client.js";
+/** Management client with all supported domain resources under `api`. */
+export declare class DeployEngineClient extends DeployEngine {
+    /** Domain resources such as `projects`, `machines`, and `securityGroups`. */
+    readonly api: {
+        projects: import("./resources/projects.js").Projects;
+        machines: import("./resources/machines.js").Machines;
+        loadBalancers: import("./resources/load-balancers.js").LoadBalancers;
+        securityGroups: import("./resources/security-groups.js").SecurityGroups;
+        workflows: import("./resources/base.js").Resource<unknown>;
+        certificates: import("./resources/base.js").Resource<unknown>;
+        domains: import("./resources/base.js").Resource<unknown>;
+        alerts: import("./resources/base.js").Resource<unknown>;
+        feedback: import("./resources/feedback.js").Feedback;
+        payments: import("./resources/payments.js").Payments;
+        authentication: import("./resources/authentication.js").Authentication;
+        tracking: import("./resources/tracking.js").TrackingAdmin;
+    };
+    /**
+     * Create a management client and install every domain resource.
+     * @example
+     * ```ts
+     * const client = new DeployEngineClient({
+     *   apiKey: process.env.DEPLOYENGINE_API_KEY
+     * })
+     * const projects = await client.api.projects.list()
+     * ```
+     */
+    constructor(options: ClientOptions);
+}

package/dist/index.js

@@ -0,0 +1,29 @@
+/** Main package entry point for management, tracking, logging, models, and errors. */
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./resources/index.js";
+export * from "./tracking/index.js";
+export * from "./logging/index.js";
+export * from "./models/index.js";
+export * from "./version.js";
+import { DeployEngine } from "./client.js";
+import { resources } from "./resources/index.js";
+/** Management client with all supported domain resources under `api`. */
+export class DeployEngineClient extends DeployEngine {
+    /** Domain resources such as `projects`, `machines`, and `securityGroups`. */
+    api;
+    /**
+     * Create a management client and install every domain resource.
+     * @example
+     * ```ts
+     * const client = new DeployEngineClient({
+     *   apiKey: process.env.DEPLOYENGINE_API_KEY
+     * })
+     * const projects = await client.api.projects.list()
+     * ```
+     */
+    constructor(options) {
+        super(options);
+        this.api = resources(this);
+    }
+}

package/dist/logging/index.d.ts

@@ -0,0 +1,2 @@
+/** Structured logging exports backed by tracking write-key ingestion. */
+export * from "./reporter.js";

package/dist/logging/index.js

@@ -0,0 +1,2 @@
+/** Structured logging exports backed by tracking write-key ingestion. */
+export * from "./reporter.js";

package/dist/logging/reporter.d.ts

@@ -0,0 +1,30 @@
+import type { Tracker } from "../tracking/tracker.js";
+/** Static service and environment labels attached to every log event. */
+export interface LogReporterContext {
+    service?: string;
+    environment?: string;
+}
+/** Per-message structured log metadata. */
+export interface LogOptions {
+    attributes?: Record<string, unknown>;
+    exception?: unknown;
+    traceId?: string;
+    userId?: string;
+}
+/** Report structured `$log` events through a browser-safe `Tracker`. */
+export declare class LogReporter {
+    private tracker;
+    private context;
+    /** Bind a tracker and optional static service/environment context. */
+    constructor(tracker: Tracker, context?: LogReporterContext);
+    /** Report a log with explicit level, attributes, exception, and trace context. */
+    log(level: string, message: string, options?: LogOptions): void;
+    /** Report a DEBUG event. */
+    debug(message: string, options?: {}): void;
+    /** Report an INFO event. */
+    info(message: string, options?: {}): void;
+    /** Report a WARNING event. */
+    warn(message: string, options?: {}): void;
+    /** Report an ERROR event. */
+    error(message: string, options?: {}): void;
+}

package/dist/logging/reporter.js

@@ -0,0 +1,38 @@
+/** Report structured `$log` events through a browser-safe `Tracker`. */
+export class LogReporter {
+    tracker;
+    context;
+    /** Bind a tracker and optional static service/environment context. */
+    constructor(tracker, context = {}) {
+        this.tracker = tracker;
+        this.context = context;
+    }
+    /** Report a log with explicit level, attributes, exception, and trace context. */
+    log(level, message, options = {}) {
+        this.tracker.track("$log", {
+            level: level.toUpperCase(),
+            message,
+            service: this.context.service,
+            environment: this.context.environment,
+            trace_id: options.traceId,
+            attributes: options.attributes ?? {},
+            exception: options.exception,
+        }, options.userId);
+    }
+    /** Report a DEBUG event. */
+    debug(message, options = {}) {
+        this.log("DEBUG", message, options);
+    }
+    /** Report an INFO event. */
+    info(message, options = {}) {
+        this.log("INFO", message, options);
+    }
+    /** Report a WARNING event. */
+    warn(message, options = {}) {
+        this.log("WARNING", message, options);
+    }
+    /** Report an ERROR event. */
+    error(message, options = {}) {
+        this.log("ERROR", message, options);
+    }
+}

package/dist/models/common.d.ts

@@ -0,0 +1,15 @@
+/** A page of API results with one-based pagination metadata. */
+export interface Page<T> {
+    items: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+}
+/** Optional controls accepted by advanced request integrations. */
+export interface RequestOptions {
+    timeoutMs?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+}

package/dist/models/common.js

@@ -0,0 +1 @@
+export {};

package/dist/models/index.d.ts

@@ -0,0 +1,4 @@
+/** Public SDK request and response models. */
+export * from "./common.js";
+export * from "./projects.js";
+export * from "./infrastructure.js";

package/dist/models/index.js

@@ -0,0 +1,4 @@
+/** Public SDK request and response models. */
+export * from "./common.js";
+export * from "./projects.js";
+export * from "./infrastructure.js";

package/dist/models/infrastructure.d.ts

@@ -0,0 +1,21 @@
+/** DeployEngine-managed load balancer summary. */
+export interface LoadBalancer {
+    id: number;
+    name: string;
+    enabled: boolean;
+    gatewayMachineId: number;
+}
+/** Host firewall policy summary. */
+export interface SecurityGroup {
+    id: number;
+    name: string;
+    description?: string;
+}
+/** Ingress or egress nftables rule accepted by security-group APIs. */
+export interface SecurityGroupRule {
+    direction: "ingress" | "egress";
+    protocol: string;
+    portStart?: number;
+    portEnd?: number;
+    source?: string;
+}

package/dist/models/infrastructure.js

@@ -0,0 +1 @@
+export {};

package/dist/models/projects.d.ts

@@ -0,0 +1,12 @@
+/** Project fields commonly returned by DeployEngine APIs. */
+export interface Project {
+    id: number;
+    name: string;
+    status?: string;
+    createdAt?: string;
+}
+/** Minimum supported body for creating a project. */
+export interface CreateProjectRequest {
+    name: string;
+    machineId?: number;
+}

package/dist/models/projects.js

@@ -0,0 +1 @@
+export {};

package/dist/resources/authentication.d.ts

@@ -0,0 +1,10 @@
+import { Resource } from "./base.js";
+/** Project-facing unified-login operations requiring the `business` scope. */
+export declare class Authentication extends Resource {
+    /** Send a verification code to an SMS phone number or email address. */
+    sendCode(kind: "sms" | "email", projectName: string, identifier: string): Promise<unknown>;
+    /** Exchange an SMS/email code for a project end-user login result. */
+    loginWithCode(kind: "sms" | "email", projectName: string, identifier: string, code: string): Promise<unknown>;
+    /** Authenticate a project end user with the password-login request body. */
+    passwordLogin(body: unknown): Promise<unknown>;
+}

package/dist/resources/authentication.js

@@ -0,0 +1,26 @@
+import { Resource } from "./base.js";
+/** Project-facing unified-login operations requiring the `business` scope. */
+export class Authentication extends Resource {
+    /** Send a verification code to an SMS phone number or email address. */
+    sendCode(kind, projectName, identifier) {
+        return this.client.request("POST", `${this.prefix}/${kind}/send-code`, {
+            body: { projectName, [kind === "sms" ? "phone" : "email"]: identifier },
+        });
+    }
+    /** Exchange an SMS/email code for a project end-user login result. */
+    loginWithCode(kind, projectName, identifier, code) {
+        return this.client.request("POST", `${this.prefix}/${kind}/login`, {
+            body: {
+                projectName,
+                [kind === "sms" ? "phone" : "email"]: identifier,
+                code,
+            },
+        });
+    }
+    /** Authenticate a project end user with the password-login request body. */
+    passwordLogin(body) {
+        return this.client.request("POST", `${this.prefix}/password/login`, {
+            body,
+        });
+    }
+}

package/dist/resources/base.d.ts

@@ -0,0 +1,18 @@
+import type { DeployEngine } from "../client.js";
+/** Generic CRUD resource used directly or extended by domain resources. */
+export declare class Resource<T = unknown> {
+    protected client: DeployEngine;
+    protected prefix: string;
+    /** Bind a management client to an API path prefix. */
+    constructor(client: DeployEngine, prefix: string);
+    /** List visible resources, optionally filtered by API query fields. */
+    list(query?: Record<string, unknown>): Promise<T[]>;
+    /** Fetch one resource by its numeric or string API identifier. */
+    get(id: string | number): Promise<T>;
+    /** Create a resource; pass an idempotency key to make retries safe. */
+    create<D = unknown>(body: D, idempotencyKey?: string): Promise<T>;
+    /** Replace a resource with the supplied request body. */
+    update<D = unknown>(id: string | number, body: D): Promise<T>;
+    /** Permanently delete one resource. */
+    delete(id: string | number): Promise<unknown>;
+}

package/dist/resources/base.js

@@ -0,0 +1,33 @@
+/** Generic CRUD resource used directly or extended by domain resources. */
+export class Resource {
+    client;
+    prefix;
+    /** Bind a management client to an API path prefix. */
+    constructor(client, prefix) {
+        this.client = client;
+        this.prefix = prefix;
+    }
+    /** List visible resources, optionally filtered by API query fields. */
+    list(query) {
+        return this.client.request("GET", this.prefix, { query });
+    }
+    /** Fetch one resource by its numeric or string API identifier. */
+    get(id) {
+        return this.client.request("GET", `${this.prefix}/${id}`);
+    }
+    /** Create a resource; pass an idempotency key to make retries safe. */
+    create(body, idempotencyKey) {
+        return this.client.request("POST", this.prefix, {
+            body,
+            idempotencyKey,
+        });
+    }
+    /** Replace a resource with the supplied request body. */
+    update(id, body) {
+        return this.client.request("PUT", `${this.prefix}/${id}`, { body });
+    }
+    /** Permanently delete one resource. */
+    delete(id) {
+        return this.client.request("DELETE", `${this.prefix}/${id}`);
+    }
+}

package/dist/resources/feedback.d.ts

@@ -0,0 +1,6 @@
+import { Resource } from "./base.js";
+/** Customer-feedback link operations in the `business` capability. */
+export declare class Feedback extends Resource {
+    /** Create a short-lived feedback submission link, optionally for a project. */
+    createTicketLink(projectId?: number): Promise<unknown>;
+}

package/dist/resources/feedback.js

@@ -0,0 +1,10 @@
+import { Resource } from "./base.js";
+/** Customer-feedback link operations in the `business` capability. */
+export class Feedback extends Resource {
+    /** Create a short-lived feedback submission link, optionally for a project. */
+    createTicketLink(projectId) {
+        return this.client.request("POST", `${this.prefix}/ticket-link`, {
+            query: { projectId },
+        });
+    }
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,35 @@
+/** Domain resource registry installed on `DeployEngineClient.api`. */
+import type { DeployEngine } from "../client.js";
+import { Authentication } from "./authentication.js";
+import { Feedback } from "./feedback.js";
+import { LoadBalancers } from "./load-balancers.js";
+import { Machines } from "./machines.js";
+import { Payments } from "./payments.js";
+import { Projects } from "./projects.js";
+import { Resource } from "./base.js";
+import { SecurityGroups } from "./security-groups.js";
+import { TrackingAdmin } from "./tracking.js";
+export * from "./base.js";
+export * from "./projects.js";
+export * from "./machines.js";
+export * from "./load-balancers.js";
+export * from "./security-groups.js";
+export * from "./payments.js";
+export * from "./authentication.js";
+export * from "./feedback.js";
+export * from "./tracking.js";
+/** Construct all resource clients with their canonical API prefixes. */
+export declare function resources(client: DeployEngine): {
+    projects: Projects;
+    machines: Machines;
+    loadBalancers: LoadBalancers;
+    securityGroups: SecurityGroups;
+    workflows: Resource<unknown>;
+    certificates: Resource<unknown>;
+    domains: Resource<unknown>;
+    alerts: Resource<unknown>;
+    feedback: Feedback;
+    payments: Payments;
+    authentication: Authentication;
+    tracking: TrackingAdmin;
+};

package/dist/resources/index.js

@@ -0,0 +1,35 @@
+import { Authentication } from "./authentication.js";
+import { Feedback } from "./feedback.js";
+import { LoadBalancers } from "./load-balancers.js";
+import { Machines } from "./machines.js";
+import { Payments } from "./payments.js";
+import { Projects } from "./projects.js";
+import { Resource } from "./base.js";
+import { SecurityGroups } from "./security-groups.js";
+import { TrackingAdmin } from "./tracking.js";
+export * from "./base.js";
+export * from "./projects.js";
+export * from "./machines.js";
+export * from "./load-balancers.js";
+export * from "./security-groups.js";
+export * from "./payments.js";
+export * from "./authentication.js";
+export * from "./feedback.js";
+export * from "./tracking.js";
+/** Construct all resource clients with their canonical API prefixes. */
+export function resources(client) {
+    return {
+        projects: new Projects(client, "/api/projects"),
+        machines: new Machines(client, "/api/machines"),
+        loadBalancers: new LoadBalancers(client, "/api/load-balancers"),
+        securityGroups: new SecurityGroups(client, "/api/security-groups"),
+        workflows: new Resource(client, "/api/workflow-tasks"),
+        certificates: new Resource(client, "/api/certificates"),
+        domains: new Resource(client, "/api/domains"),
+        alerts: new Resource(client, "/api/alert/contacts"),
+        feedback: new Feedback(client, "/api/feedback"),
+        payments: new Payments(client, "/api/orders"),
+        authentication: new Authentication(client, "/api/unified-login"),
+        tracking: new TrackingAdmin(client, "/api/tracking"),
+    };
+}

package/dist/resources/load-balancers.d.ts

@@ -0,0 +1,10 @@
+import { Resource } from "./base.js";
+/** DeployEngine-managed load balancer operations (`infrastructure` scope). */
+export declare class LoadBalancers extends Resource {
+    /** Partially update a load balancer from an API request body. */
+    update(id: string | number, body: unknown): Promise<unknown>;
+    /** Synchronize configuration to its gateway using a stable retry key. */
+    sync(id: number): Promise<unknown>;
+    /** Bind a project with an optional listener/upstream binding specification. */
+    bindProject(id: number, projectId: number, bindingSpec?: {}): Promise<unknown>;
+}

package/dist/resources/load-balancers.js

@@ -0,0 +1,20 @@
+import { Resource } from "./base.js";
+/** DeployEngine-managed load balancer operations (`infrastructure` scope). */
+export class LoadBalancers extends Resource {
+    /** Partially update a load balancer from an API request body. */
+    update(id, body) {
+        return this.client.request("PATCH", `${this.prefix}/${id}`, { body });
+    }
+    /** Synchronize configuration to its gateway using a stable retry key. */
+    sync(id) {
+        return this.client.request("POST", `${this.prefix}/${id}/sync`, {
+            idempotencyKey: `lb-sync-${id}`,
+        });
+    }
+    /** Bind a project with an optional listener/upstream binding specification. */
+    bindProject(id, projectId, bindingSpec = {}) {
+        return this.client.request("POST", `${this.prefix}/${id}/projects`, {
+            body: { projectId, bindingSpec },
+        });
+    }
+}

package/dist/resources/machines.d.ts

@@ -0,0 +1,8 @@
+import { Resource } from "./base.js";
+/** Machine inventory and diagnostics operations requiring `machines` scope. */
+export declare class Machines extends Resource {
+    /** Recommend machine sizing from the supplied workload requirements. */
+    recommendations(body: unknown): Promise<unknown>;
+    /** Return the current DeployEngine Agent state for a machine. */
+    agentStatus(id: number): Promise<unknown>;
+}

package/dist/resources/machines.js

@@ -0,0 +1,14 @@
+import { Resource } from "./base.js";
+/** Machine inventory and diagnostics operations requiring `machines` scope. */
+export class Machines extends Resource {
+    /** Recommend machine sizing from the supplied workload requirements. */
+    recommendations(body) {
+        return this.client.request("POST", "/api/machines/recommendations", {
+            body,
+        });
+    }
+    /** Return the current DeployEngine Agent state for a machine. */
+    agentStatus(id) {
+        return this.client.request("GET", `/api/machines/${id}/agent/status`);
+    }
+}

package/dist/resources/payments.d.ts

@@ -0,0 +1,11 @@
+import { Resource } from "./base.js";
+/** Unified-payment operations requiring the `business` scope. */
+export declare class Payments extends Resource {
+    /**
+     * Create a payment order.
+     * Reuse `idempotencyKey` only for retries of the same logical order.
+     */
+    createOrder(body: unknown, idempotencyKey?: string): Promise<unknown>;
+    /** Request a partial or full refund in the API's configured fee unit. */
+    refund(orderNo: string, refundFee: number, reason?: string): Promise<unknown>;
+}

package/dist/resources/payments.js

@@ -0,0 +1,20 @@
+import { Resource } from "./base.js";
+/** Unified-payment operations requiring the `business` scope. */
+export class Payments extends Resource {
+    /**
+     * Create a payment order.
+     * Reuse `idempotencyKey` only for retries of the same logical order.
+     */
+    createOrder(body, idempotencyKey) {
+        return this.client.request("POST", "/api/orders/create_v2", {
+            body,
+            idempotencyKey,
+        });
+    }
+    /** Request a partial or full refund in the API's configured fee unit. */
+    refund(orderNo, refundFee, reason) {
+        return this.client.request("POST", `/api/orders/${orderNo}/refund`, {
+            body: { refundFee, reason },
+        });
+    }
+}

package/dist/resources/projects.d.ts

@@ -0,0 +1,22 @@
+import { Resource } from "./base.js";
+/** Project, deployment, and release operations (`read`/`deploy` scopes). */
+export declare class Projects extends Resource {
+    /** List deployment records belonging to a project. */
+    deployments(id: number): Promise<unknown>;
+    /** List release-history records belonging to a project. */
+    releases(id: number): Promise<unknown>;
+    /** Validate deployment configuration without starting a deployment. */
+    precheck(id: number, body: unknown): Promise<unknown>;
+    /**
+     * Start a deployment and asynchronously yield decoded SSE progress events.
+     * @example
+     * ```ts
+     * for await (const event of client.api.projects.deployStream(7, body)) {
+     *   console.log(event)
+     * }
+     * ```
+     */
+    deployStream(id: number, body: unknown): AsyncGenerator<unknown, any, any>;
+    /** Restart a deployed project and yield its SSE progress events. */
+    restartStream(id: number, body?: unknown): AsyncGenerator<unknown, any, any>;
+}

package/dist/resources/projects.js

@@ -0,0 +1,34 @@
+import { Resource } from "./base.js";
+/** Project, deployment, and release operations (`read`/`deploy` scopes). */
+export class Projects extends Resource {
+    /** List deployment records belonging to a project. */
+    deployments(id) {
+        return this.client.request("GET", `/api/projects/${id}/deployments`);
+    }
+    /** List release-history records belonging to a project. */
+    releases(id) {
+        return this.client.request("GET", `/api/projects/${id}/release-history`);
+    }
+    /** Validate deployment configuration without starting a deployment. */
+    precheck(id, body) {
+        return this.client.request("POST", `/api/projects/${id}/deploy-precheck`, {
+            body,
+        });
+    }
+    /**
+     * Start a deployment and asynchronously yield decoded SSE progress events.
+     * @example
+     * ```ts
+     * for await (const event of client.api.projects.deployStream(7, body)) {
+     *   console.log(event)
+     * }
+     * ```
+     */
+    deployStream(id, body) {
+        return this.client.stream("POST", `/api/projects/${id}/deploy-stream`, body);
+    }
+    /** Restart a deployed project and yield its SSE progress events. */
+    restartStream(id, body = {}) {
+        return this.client.stream("POST", `/api/projects/${id}/restart-stream`, body);
+    }
+}

package/dist/resources/security-groups.d.ts

@@ -0,0 +1,10 @@
+import { Resource } from "./base.js";
+/** Host firewall policy operations requiring `infrastructure` scope. */
+export declare class SecurityGroups extends Resource {
+    /** Partially update a DeployEngine-managed nftables security group. */
+    update(id: string | number, body: unknown): Promise<unknown>;
+    /** Apply the current policy to associated machines using a stable retry key. */
+    apply(id: number): Promise<unknown>;
+    /** Add a firewall rule; provide an idempotency key for safe retries. */
+    addRule(id: number, body: unknown, idempotencyKey?: string): Promise<unknown>;
+}

package/dist/resources/security-groups.js

@@ -0,0 +1,21 @@
+import { Resource } from "./base.js";
+/** Host firewall policy operations requiring `infrastructure` scope. */
+export class SecurityGroups extends Resource {
+    /** Partially update a DeployEngine-managed nftables security group. */
+    update(id, body) {
+        return this.client.request("PATCH", `${this.prefix}/${id}`, { body });
+    }
+    /** Apply the current policy to associated machines using a stable retry key. */
+    apply(id) {
+        return this.client.request("POST", `${this.prefix}/${id}/apply`, {
+            idempotencyKey: `sg-apply-${id}`,
+        });
+    }
+    /** Add a firewall rule; provide an idempotency key for safe retries. */
+    addRule(id, body, idempotencyKey) {
+        return this.client.request("POST", `${this.prefix}/${id}/rules`, {
+            body,
+            idempotencyKey,
+        });
+    }
+}

package/dist/resources/tracking.d.ts

@@ -0,0 +1,6 @@
+import { Resource } from "./base.js";
+/** Low-level event ingestion using a project-scoped tracking write key. */
+export declare class TrackingAdmin extends Resource {
+    /** Send an event batch without exposing a management API key. */
+    collect(appId: string, projectName: string, writeKey: string, events: unknown[]): Promise<unknown>;
+}

package/dist/resources/tracking.js

@@ -0,0 +1,12 @@
+import { Resource } from "./base.js";
+/** Low-level event ingestion using a project-scoped tracking write key. */
+export class TrackingAdmin extends Resource {
+    /** Send an event batch without exposing a management API key. */
+    collect(appId, projectName, writeKey, events) {
+        return this.client.request("POST", `${this.prefix}/v1/collect`, {
+            headers: { "X-Write-Key": writeKey },
+            body: { app_id: appId, project_name: projectName, events },
+            idempotencyKey: `tracking-${appId}-${crypto.randomUUID()}`,
+        });
+    }
+}

package/dist/tracking/index.d.ts

@@ -0,0 +1,2 @@
+/** Browser-safe tracking exports; use only project-scoped write keys. */
+export * from "./tracker.js";

package/dist/tracking/index.js

@@ -0,0 +1,2 @@
+/** Browser-safe tracking exports; use only project-scoped write keys. */
+export * from "./tracker.js";

package/dist/tracking/tracker.d.ts

@@ -0,0 +1,29 @@
+/** Browser-safe event tracker configuration. */
+export interface TrackerOptions {
+    /** DeployEngine public origin. */
+    baseUrl: string;
+    appId: string;
+    projectName: string;
+    writeKey: string;
+    /** Flush immediately when the queue reaches this size. Defaults to 20. */
+    flushAt?: number;
+    /** Periodic flush interval; set to zero to disable. Defaults to 5000 ms. */
+    flushIntervalMs?: number;
+}
+/** Queue and deliver browser-safe analytics events using a tracking write key. */
+export declare class Tracker {
+    private options;
+    private queue;
+    private timer?;
+    private anonymousId;
+    constructor(options: TrackerOptions);
+    /** Queue an event and flush automatically when `flushAt` is reached. */
+    track(event: string, properties?: Record<string, unknown>, userId?: string): void;
+    /** Associate an anonymous visitor with an application user and traits. */
+    identify(anonymousId: string, userId: string, traits?: Record<string, unknown>): Promise<any>;
+    /** Deliver queued events; failed batches are restored for a later retry. */
+    flush(): Promise<void>;
+    /** Stop periodic delivery and flush all remaining events. */
+    close(): Promise<void>;
+    private send;
+}

package/dist/tracking/tracker.js

@@ -0,0 +1,72 @@
+/** Queue and deliver browser-safe analytics events using a tracking write key. */
+export class Tracker {
+    options;
+    queue = [];
+    timer;
+    anonymousId = crypto.randomUUID();
+    constructor(options) {
+        this.options = options;
+        if (options.flushIntervalMs !== 0)
+            this.timer = setInterval(() => void this.flush(), options.flushIntervalMs ?? 5000);
+    }
+    /** Queue an event and flush automatically when `flushAt` is reached. */
+    track(event, properties = {}, userId) {
+        this.queue.push({
+            event_name: event,
+            properties,
+            user_id: userId,
+            anonymous_id: this.anonymousId,
+            timestamp: new Date().toISOString(),
+            event_id: crypto.randomUUID(),
+        });
+        if (this.queue.length >= (this.options.flushAt ?? 20))
+            void this.flush();
+    }
+    /** Associate an anonymous visitor with an application user and traits. */
+    identify(anonymousId, userId, traits = {}) {
+        return this.send("/api/tracking/v1/identify", {
+            app_id: this.options.appId,
+            project_name: this.options.projectName,
+            anonymous_id: anonymousId,
+            user_id: userId,
+            traits,
+        });
+    }
+    /** Deliver queued events; failed batches are restored for a later retry. */
+    async flush() {
+        if (!this.queue.length)
+            return;
+        const events = this.queue.splice(0);
+        try {
+            await this.send("/api/tracking/v1/collect", {
+                app_id: this.options.appId,
+                project_name: this.options.projectName,
+                events,
+            });
+        }
+        catch (error) {
+            this.queue.unshift(...events);
+            throw error;
+        }
+    }
+    /** Stop periodic delivery and flush all remaining events. */
+    close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        return this.flush();
+    }
+    async send(path, body) {
+        const response = await fetch(`${this.options.baseUrl.replace(/\/$/, "")}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Write-Key": this.options.writeKey,
+            },
+            body: JSON.stringify(body),
+            keepalive: true,
+        });
+        if (!response.ok)
+            throw new Error(`Tracking request failed (${response.status})`);
+        return response.json();
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Installed SDK version included in diagnostic request headers. */
+export declare const VERSION = "1.0.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Installed SDK version included in diagnostic request headers. */
+export const VERSION = "1.0.0";

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "creat01deployengine",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for DeployEngine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tracking": {
+      "types": "./dist/tracking/index.d.ts",
+      "import": "./dist/tracking/index.js"
+    },
+    "./logging": {
+      "types": "./dist/logging/index.d.ts",
+      "import": "./dist/logging/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AI_USAGE.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "keywords": [],
+  "author": ""
+}