Class ApplicationsClient

constructor

• new ApplicationsClient(
      call: Caller,
      callPublic: Caller,
      hooks?: OperationHooks,
  ): ApplicationsClient

  Parameters

  • call: Caller
  • callPublic: Caller
  • hooks: OperationHooks = {}

  Returns ApplicationsClient

ReadonlyapiKeys

Readonlyauth

Readonlycertificates

Readonlydeclarations

ReadonlyshortCodes

accessDecisions

• accessDecisions(
      params: { applicationId: string; cursor?: string; limit?: number },
      opts?: RequestOptions,
  ): Promise<ApplicationAccessDecisionsPage>

  Access-decision events for an application (gateway-security C5 / GS-7): gateway-side denials (IP allow/deny, abuse rate trips, unknown-host, suspension) aggregated per 60s window, newest-first. Org-scoped by the backend against the application's OWNER org — the caller must belong to it.

  Paginated: pass limit (default 100, max 500) and an opaque cursor from a prior page's nextCursor.

  Parameters

  • params: { applicationId: string; cursor?: string; limit?: number }
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationAccessDecisionsPage>

checkReachability

• checkReachability(
      applicationId: string,
      opts?: RequestOptions,
  ): Promise<CheckApplicationReachabilityResponse>

  Probe the application's public URL and report reachability.

  Parameters

  • applicationId: string
  • Optionalopts: RequestOptions

  Returns Promise<CheckApplicationReachabilityResponse>

create

• create(
      req: {} | CreateApplicationRequest,
      opts?: RequestOptions,
  ): Promise<ApplicationData>

  Create an application record.

  The backend accepts ONLY canonical apiVersion: v3 Application documents (declarative-config phase 2a). Canonical documents are sent unchanged; the legacy flat CreateApplicationRequest shape is translated to a canonical document first (see legacyCreateTranslator.ts) and throws ValidationError (LEGACY_CREATE_UNSUPPORTED_FIELD) for flat fields with no canonical equivalent — nothing is silently dropped.

  Parameters

  • req: {} | CreateApplicationRequest
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationData>

  Throws

  ConflictError if the application name is already in use (APPLICATION_NAME_ALREADY_IN_USE).

  Throws

  ValidationError if a legacy flat request cannot be translated.

delete

• delete(applicationId: string, opts?: RequestOptions): Promise<void>

  Delete an application.

  Parameters

  • applicationId: string
  • Optionalopts: RequestOptions

  Returns Promise<void>

  Throws

  NotFoundError if the application does not exist.

deploy

• deploy(
      applicationId: string,
      req: DeployApplicationRequest,
      opts?: RequestOptions,
  ): Promise<Operation<ApplicationDeclarationApplied>>

  Apply a canonical declaration (the kick-off — Operation.resource is the new version stamp) and return an Operation whose waiter polls the deployment status to 'ready'.

  Parameters

  • applicationId: string
  • req: DeployApplicationRequest
  • Optionalopts: RequestOptions

  Returns Promise<Operation<ApplicationDeclarationApplied>>

  Throws

  NotFoundError if the application does not exist.

  Example

  const op = await sdk.applications.deploy(appId, { canonical });
  await op.waitUntilReady({ onProgress: (s) => console.log(s.phase) });
  Copy

get

• get(applicationId: string, opts?: RequestOptions): Promise<ApplicationData>

  Fetch an application by id.

  Parameters

  • applicationId: string
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationData>

  Throws

  NotFoundError if the application does not exist.

getDeploymentStatus

• getDeploymentStatus(
      applicationId: string,
      opts?: RequestOptions,
  ): Promise<ApplicationDeploymentStatus>

  Current deployment FSM state plus recent history (the deploy waiter's poll target).

  Parameters

  • applicationId: string
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationDeploymentStatus>

  Throws

  NotFoundError if the application does not exist.

getGatewayInfo

• getGatewayInfo(
      params: { applicationId: string },
      opts?: RequestOptions,
  ): Promise<CustomerGatewayInfo[]>

  The gateway(s) an application routes through, as a customer-facing projection (webapp gateway panel). Per gateway: display name, kind (managed | customer), hostname, region, real WS-heartbeat health, last-seen, and this app's HAProxy backend server states. Managed gateways live under the platform org and are never browsable devices — this is the only customer read of them. Excludes SSH / capacity / other orgs' apps.

  App-ownership scoped (org owns the app ⇒ may read its gateway projection).

  Parameters

  • params: { applicationId: string }
  • Optionalopts: RequestOptions

  Returns Promise<CustomerGatewayInfo[]>

  the gateway projections; an unpublished app returns [].

getLifecycleEvents

• getLifecycleEvents(
      params: {
          applicationId: string;
          endTime?: number;
          limit?: number;
          organizationId: string;
          startTime?: number;
      },
      opts?: RequestOptions,
  ): Promise<LifecycleEvent[]>

  Lifecycle event history (newest-first, backend default limit 100).

  Parameters

  • params: {
        applicationId: string;
        endTime?: number;
        limit?: number;
        organizationId: string;
        startTime?: number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<LifecycleEvent[]>

getLogs

• getLogs(
      params: {
          applicationId: string;
          endTime: number;
          eventType?: EventType;
          level?: LogLevel;
          organizationId: string;
          startTime: number;
      },
      opts?: RequestOptions,
  ): Promise<ApplicationLogsResult>

  Logs over a unix-ms window, optionally filtered by level/eventType.

  Parameters

  • params: {
        applicationId: string;
        endTime: number;
        eventType?: EventType;
        level?: LogLevel;
        organizationId: string;
        startTime: number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationLogsResult>

getMetrics

• getMetrics(
      params: {
          applicationId: string;
          endTime: number;
          organizationId: string;
          startTime: number;
      },
      opts?: RequestOptions,
  ): Promise<ApplicationMetrics>

  Aggregated metrics over a unix-ms window.

  Parameters

  • params: {
        applicationId: string;
        endTime: number;
        organizationId: string;
        startTime: number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationMetrics>

getMetricsFiles

• getMetricsFiles(
      params: {
          applicationId: string;
          endTime: number;
          interval?: "5min" | "hourly";
          organizationId: string;
          startTime: number;
      },
      opts?: RequestOptions,
  ): Promise<LogFilesResponse>

  Pre-signed metric-file URLs over a unix-ms window. Route is the backend's /metrics-files (the legacy client's /metrics/files path does not exist in routeDefinitions).

  Parameters

  • params: {
        applicationId: string;
        endTime: number;
        interval?: "5min" | "hourly";
        organizationId: string;
        startTime: number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<LogFilesResponse>

getSecrets

• getSecrets(
      params: { applicationId: string },
      opts?: RequestOptions,
  ): Promise<ResolvedApplicationSecrets>

  Resolve the secret keys the application's current declaration references, flattened to environment variables (design/secrets-management §7). This is the DEVICE-authenticated, deploy-time path used by the agent — the only secrets endpoint that returns values, scoped to the assigned app's keys.

  Parameters

  • params: { applicationId: string }
  • Optionalopts: RequestOptions

  Returns Promise<ResolvedApplicationSecrets>

  Throws

  AuthorizationError if the caller is not a device assigned the app.

getTraffic

• getTraffic(
      params: {
          access?: string;
          applicationId: string;
          end?: string | number;
          granularity?: TrafficGranularity;
          organizationId: string;
          route?: string;
          start?: string | number;
      },
      opts?: RequestOptions,
  ): Promise<TrafficSummary>

  Edge request telemetry summary (ADR-0026): per-minute or hourly request counts, status classes, bytes, derived latency percentiles, top paths / clients / user agents, and forward-auth outcomes, as observed by Caddy on the application's serving devices. start/end are epoch ms or ISO instants (default: the last 24 h); granularity defaults to minute for ranges up to 6 h and hour beyond. Every count is a sum over the range; asOf names the newest delivered minute — Firehose buffering makes the view near-real-time, never live.

  Parameters

  • params: {
        access?: string;
        applicationId: string;
        end?: string | number;
        granularity?: TrafficGranularity;
        organizationId: string;
        route?: string;
        start?: string | number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<TrafficSummary>

getVmSshKey

• getVmSshKey(applicationId: string, opts?: RequestOptions): Promise<string>

  PEM private key for a VM application (used by application ssh).

  Parameters

  • applicationId: string
  • Optionalopts: RequestOptions

  Returns Promise<string>

getWorkloadLogs

• getWorkloadLogs(
      params: {
          applicationId: string;
          deviceId?: string;
          limit?: number;
          priority?: "debug" | "info" | "warning" | "err";
          since?: string | number;
      },
      opts?: RequestOptions,
  ): Promise<WorkloadLogsResponse>

  P3-1 — live workload logs collected on demand from the app's serving device(s) over the diagnostics jobs channel (GET /applications/{id}/logs). This is the LIVE path (works before anything reaches S3 and when an app is wedged); getLogs is the separate historical S3 lifecycle/metrics stream. An offline device yields a block with offline: true (not an error).

  Parameters

  • params: {
        applicationId: string;
        deviceId?: string;
        limit?: number;
        priority?: "debug" | "info" | "warning" | "err";
        since?: string | number;
    }
  • Optionalopts: RequestOptions

  Returns Promise<WorkloadLogsResponse>

listRequests

• listRequests(
      params: {
          access?: string;
          applicationId: string;
          clientIp?: string;
          cursor?: string;
          end?: string | number;
          limit?: number;
          organizationId: string;
          path?: string;
          start?: string | number;
          status?: string;
      },
      opts?: RequestOptions,
  ): Promise<TrafficRequestsPage>

  Raw request records (ADR-0026): every 4xx/5xx and upstream error plus a sample of the rest, newest first, over a window of at most 6 h (default: the last 6 h). Filter by status (5xx, 404, 400-499), a path prefix, an exact clientIp or an access name; page with cursor.

  Parameters

  • params: {
        access?: string;
        applicationId: string;
        clientIp?: string;
        cursor?: string;
        end?: string | number;
        limit?: number;
        organizationId: string;
        path?: string;
        start?: string | number;
        status?: string;
    }
  • Optionalopts: RequestOptions

  Returns Promise<TrafficRequestsPage>

redeploy

• redeploy(
      params: { applicationId: string },
      opts?: RequestOptions,
  ): Promise<ApplicationRedeployResult>

  Force re-realization of the CURRENT release without cutting a new version. Bumps the app-level redeployToken so serving agents force-recreate the workload; ref-neutral (currentReleaseVersion is untouched).

  Parameters

  • params: { applicationId: string }
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationRedeployResult>

  Throws

  NotFoundError if the application does not exist.

  Throws

  ConflictError if the application has no cut release to redeploy.

rolloutStatus

• rolloutStatus(
      params: { applicationId: string },
      opts?: RequestOptions,
  ): Promise<ApplicationRolloutStatus>

  Per-device convergence toward the current release (a pure read). Each device is converged iff its observedReleaseVersion strictly equals the app's currentReleaseVersion.

  Parameters

  • params: { applicationId: string }
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationRolloutStatus>

  Throws

  NotFoundError if the application does not exist.

trace

• trace(
      params: { applicationId: string; timeoutMs?: number },
      opts?: RequestOptions,
  ): Promise<AppTraceResponse>

  Correlated hop-by-hop data-path trace for an application (CP-3.1). The backend fans collect_diagnostics to the app's gateway + serving devices and joins the hops — gateway HAProxy backend state → WireGuard handshake age → serving Caddy route/cert → workload health — into one AppTraceResponse carrying a verdict (ok | fail | unknown) per hop.

  timeoutMs is an optional client budget; the handler caps it under the API Gateway 29s ceiling regardless. An offline device yields unknown hops (with a reason) rather than an error.

  Parameters

  • params: { applicationId: string; timeoutMs?: number }
  • Optionalopts: RequestOptions

  Returns Promise<AppTraceResponse>

update

• update(
      req: UpdateApplicationRequest,
      opts?: RequestOptions,
  ): Promise<ApplicationData>

  Update an application record; returns the updated row.

  Parameters

  • req: UpdateApplicationRequest
  • Optionalopts: RequestOptions

  Returns Promise<ApplicationData>

  Throws

  NotFoundError if the application does not exist.

updateStatus

• updateStatus(
      params: { applicationId: string; status: ApplicationRuntimeStatus },
      opts?: RequestOptions,
  ): Promise<void>

  Set the application's runtime status (reported per serving device).

  Parameters

  • params: { applicationId: string; status: ApplicationRuntimeStatus }
  • Optionalopts: RequestOptions

  Returns Promise<void>

watchDeployment

• watchDeployment(
      applicationId: string,
      opts?: { targetReleaseVersion?: number },
  ): Operation<{ applicationId: string }>

  Watch an ALREADY-applied deployment to a terminal state WITHOUT re-applying (unlike deploy, which cuts a new version). This is the deploy waiter for a stack whose versions were already cut via stacks.deploy — it polls the same deployment-status FSM to 'ready'/'degraded' (or throws WaiterError on error/timeout — degraded is converged-with-warning, not failure). resource echoes the app id being watched.

  Pass targetReleaseVersion — the version this deploy cut — whenever it is known. It scopes failures to the release being waited on, so an error reported for an EARLIER release is not mistaken for this deploy's outcome (the create window; see deploymentPollResult).

  Parameters

  • applicationId: string
  • Optionalopts: { targetReleaseVersion?: number }

  Returns Operation<{ applicationId: string }>

  Example

  const op = sdk.applications.watchDeployment(appId, { targetReleaseVersion: 2 });
  await op.waitUntilReady({ onProgress: (s) => render(s) });
  Copy