Class ApplicationsClient

constructor

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

  Parameters

  • call: 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.

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>

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): 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.

  Parameters

  • applicationId: string

  Returns Operation<{ applicationId: string }>

  Example

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