@elaraai/e3-cloud-client 0.0.0-stage → 1.0.90

package/LICENSE.md

@@ -0,0 +1,54 @@
+# Business Source License 1.1
+
+Copyright (c) 2025 Elara AI Pty Ltd
+
+## License
+
+**Licensor:** Elara AI Pty Ltd
+
+**Licensed Work:** @elaraai/e3-cloud-client
+
+**Change Date:** Four years from the date of each release
+
+**Change License:** AGPL-3.0
+
+## Terms
+
+The Licensed Work is provided under the terms of the Business Source License 1.1 as detailed below.
+
+### Grant of Rights
+
+The Licensor grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
+
+### Production Use Limitation
+
+**"Production Use"** means any use by or on behalf of a for-profit entity, other than for evaluation, testing, or development purposes.
+
+Production Use requires a separate commercial license from the Licensor.
+
+### Change Date
+
+On the Change Date (four years after each release), the Licensed Work will be made available under the Change License (AGPL-3.0).
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+### Package-Specific Licenses
+
+Individual packages within this repository may have different licensing terms. See the LICENSE.md file in each package directory for details.
+
+## Commercial Licensing
+
+To obtain a commercial license for Production Use, contact:
+
+**Email:** support@elara.ai
+**Website:** https://elaraai.com
+
+## Governing Law
+
+This license is governed by the laws of New South Wales, Australia.
+
+---
+
+*Elara AI Pty Ltd*

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# @elaraai/e3-cloud-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+HTTP client library for the e3 cloud API: what e3's own API client
+(`@elaraai/e3-api-client`) doesn't cover — users and roles, schedules, task
+configs, secrets, record history and backups, feedback, apps, releases and
+staging, and rack delegation.
+
+## Installation
+
+```bash
+npm install @elaraai/e3-cloud-client
+```
+
+## Usage
+
+```typescript
+import { whoami, repoUsers, addUser, removeUser, ApiError } from '@elaraai/e3-cloud-client';
+import { variant } from '@elaraai/east';
+
+const options = { token: 'my-access-token' };
+
+// Get current user
+const me = await whoami('https://e3.example.com', options);
+console.log(`Logged in as ${me.sub}, admin: ${me.isAdmin}`);
+
+// List users on a repo
+const users = await repoUsers('https://e3.example.com', 'my-repo', options);
+
+// Add a user holding business roles
+const newUser = await addUser(
+  'https://e3.example.com',
+  'my-repo',
+  { email: 'bob@example.com', role: variant('user', { roles: ['Rostering'] }) },
+  options
+);
+
+// Remove a user
+await removeUser('https://e3.example.com', 'my-repo', 'user-id', options);
+```
+
+## API
+
+### `whoami(url, options): Promise<WhoamiResponse>`
+
+Get current user info.
+
+### `repoUsers(url, repo, options): Promise<RepoUser[]>`
+
+List the people of a repository (owner or admin).
+
+### `addUser(url, repo, request, options): Promise<RepoUser>`
+
+Add a person to a repository, or change their role: an owner, or a user holding business roles the repository has (or the built-in `All apps`). 400 `bad_request` for a role it does not have.
+
+### Business roles
+
+| Function | Answers |
+|---|---|
+| `listRoles(url, repo, options)` | A repository's roles, by name (owner or admin) |
+| `getRole(url, repo, name, options)` | One; 404 `not_found` |
+| `putRole(url, repo, role, options)` | Writes it whole, made or replaced, and answers it as stored; 400 `invalid_name` or `bad_request` (an app twice, no page, a page an app does not have). An app not deployed yet may be granted |
+| `deleteRole(url, repo, name, options)` | Removes it, idempotently; 409 `role_in_use` while anyone holds it |
+| `myAccess(url, options)` | What the caller's roles grant: each app, with its pages, in the repositories it is no owner of |
+
+### `removeUser(url, repo, userId, options): Promise<void>`
+
+Remove a user from a repository.
+
+### The deployment's people (admin)
+
+| Function | Answers |
+|---|---|
+| `listAdminUsers(url, options)` | Every person: the directory's users, the pending invitations, each one's memberships and last sign-in (Admin › Users) |
+| `lookupPeople(url, { subs?, emails? }, options)` | The people of the given subjects and emails the directory holds (`PersonList`: each one's sub, email, name and whether they may sign in), each once: what a page needs to name who did something, never the whole directory. At most `PEOPLE_LOOKUP_MAX` (100) keys |
+| `disableUser(url, sub, options)`, `enableUser(url, sub, options)` | Blocks or restores a person's sign-in; never the caller's own |
+
+### `listCompute(url, repo, workspace, options): Promise<ComputeConfigMap>`
+
+List all compute configs for a workspace.
+
+### `getCompute(url, repo, workspace, taskName, options): Promise<ComputeSize>`
+
+Get the compute size for a task.
+
+### `setCompute(url, repo, workspace, taskName, size, options): Promise<ComputeSize>`
+
+Set the compute size for a task.
+
+### `setComputeBatch(url, repo, workspace, configs, options): Promise<ComputeConfigMap>`
+
+Batch set compute configs for a workspace.
+
+### `removeCompute(url, repo, workspace, taskName, options): Promise<void>`
+
+Remove the compute config for a task.
+
+### `listTimeout(url, repo, workspace, options): Promise<TimeoutConfigMap>`
+
+List all timeout configs for a workspace.
+
+### `getTimeout(url, repo, workspace, taskName, options): Promise<TaskTimeout>`
+
+Get the timeout for a task. Returns the effective default (15m for serverless, 1440m for sized) if not explicitly set.
+
+### `setTimeout(url, repo, workspace, taskName, timeout, options): Promise<TaskTimeout>`
+
+Set the timeout for a task.
+
+### `setTimeoutBatch(url, repo, workspace, configs, options): Promise<TimeoutConfigMap>`
+
+Batch set timeout configs for a workspace.
+
+### `removeTimeoutBatch(url, repo, workspace, taskNames, options): Promise<TimeoutConfigMap>`
+
+Remove several tasks' timeouts in one request (`POST …/task-configs/timeout/remove`); answers those left. A compute config is removed in a batch by setting the task `serverless` (`setComputeBatch`).
+
+### `removeTimeout(url, repo, workspace, taskName, options): Promise<void>`
+
+Remove the timeout config for a task.
+
+### `listTaskConfigs(url, repo, workspace, options): Promise<TaskConfigs>`
+
+List all task configs (compute + timeout) for a workspace.
+
+### `repositorySettings(url, repo, options): Promise<RepositorySettings>`
+
+Every workspace of a repository's settings in one request (owner or admin):
+each one's task configs, task and function delegations, dataflow width (as
+`getWidth` answers it), feedback switch and last run's summary
+(`WorkspaceSettings`, by workspace).
+
+### Feedback
+
+Notes users send about a part of a workspace's pages (`FB-<number>`). Owners,
+admins, and users in a workspace they are granted an app of send and read
+their own; owners and admins read every note, close and reopen them, and turn
+feedback on or off.
+
+| Function | Answers |
+|---|---|
+| `getFeedbackSettings(url, repo, ws, options)` | `{ enabled }` |
+| `putFeedbackSettings(url, repo, ws, enabled, options)` | `{ enabled }` (owner or admin) |
+| `addFeedback(url, repo, ws, request, options)` | `{ id, number }`; `feedback_disabled` while off, `bad_request` past a limit |
+| `listMyFeedback(url, repo, ws, options, { status?, limit?, cursor? })` | `FeedbackMine`: the caller's own summaries, newest first, and `next` |
+| `listFeedback(url, repo, ws, options, { status?, limit?, cursor? })` | `FeedbackList`: the workspace's notes, whole, `next` and `counts` (owner or admin) |
+| `getFeedback(url, repo, ws, number, options, { status? })` | `FeedbackNote` (owner or admin, or its sender); `not_found` |
+| `feedbackScreenshotUrl(url, repo, ws, number, options, { status? })` | a URL good for 15 minutes, fetched without the API's auth |
+| `closeFeedback(url, repo, ws, number, options)`, `reopenFeedback(…)` | `FeedbackNote`, moved (owner or admin) |
+
+`status` is `'open'` (the default for lists) or `'closed'`; passing it to a
+note's reads saves the server a read. The `Feedback*` types and the limits
+(`FEEDBACK_*`, `feedbackId`) are re-exported from `@elaraai/e3-cloud-types`.
+
+### Apps
+
+Pages and menus deployed to a workspace, each its own deployable, built with
+`@elaraai/e3-cloud-ui`. Owners and admins read every app, and a user the apps
+their business roles grant; owners and admins upload, deploy, list versions
+and remove.
+
+| Function | Answers |
+|---|---|
+| `appList(url, repo, ws, options)` | the workspace's apps (`AppSummary[]`), each its current version |
+| `appGet(url, repo, ws, app, options)` | `AppSummary`; `not_found` |
+| `appVersions(url, repo, ws, app, options, { limit?, cursor? })` | `AppVersionPage`: kept versions, newest first, and `next` |
+| `appUpload(url, repo, ws, app, bytes, options)` | the source a deploy names: asks where the app object's bytes go and PUTs them there |
+| `appDeploy(url, repo, ws, app, { source, forPlatform, dryRun }, options)` | `AppDeployResponse`: `refused` (every problem), `checked`, `live` or `staged` |
+| `appsDeploy(url, repo, ws, { apps, forPlatform, dryRun }, options)` | the same, for several apps together |
+| `appRemove(url, repo, ws, app, options)` | `{ name, users }`: `users` is empty (a business role's grant of the app is kept, and gives it again if it is deployed again) |
+| `appDeployWait(url, repo, ws, job, options, { onProgress?, signal?, refresh?, deadlineMs? })` | `WorkspaceDeployResult`: waits for the deploy job an app deployed with its package started (`deploying`), polling e3's `GET …/deploy/:id` (100 ms, backing off to 1 s, and to 5 s once the job has run a minute); `refresh` gives each poll its request options afresh (a token refreshed as it expires, for a deploy that outlives it); `deadlineMs` stops waiting (the job runs on); its apps are live once it completes; throws when the deploy fails, and the apps stay as they were |
+| `myAppList(url, options)` | `AppList`: the apps you can open across the repositories you belong to — every app of each repository you own but a staging workspace's, and the apps your business roles grant — by repository, workspace and name; the console's sidebar lists them, `myAccess` says which pages |
+| `repositoryAppList(url, repo, options)` | `RepositoryApps` (owner or admin): the repository's apps in every workspace, each its current version and any staged bundle, with the e3 the platform runs (`platform`): an app built with another e3 and with no bundle staged for it needs a rebuild |
+| `myAppRebuilds(url, options)` | `AppRebuilds`: the apps that need a rebuild in the repositories you manage (every repository, for an admin; those you own, else), each built with another e3 than the platform runs with no bundle built with it staged, by repository, workspace and name, with the e3 the platform runs (`platform`); a platform deploy is refused while one has no build for the e3 it deploys |
+| `adminAppList(url, options, { limit?, cursor? })` | `AdminAppPage` (admin): a page of the deployment's apps by repository, workspace and name, `next`, the e3 the platform runs (`platform`), and when each of the page's workspaces was last released to (`lastReleases`) |
+
+A deploy throws `ApiError` with `package_missing` (import the package, then
+deploy), `package_version_conflict`, `package_deploy_unavailable` (a server
+that deploys no package with its apps), `package_differs`, `app_conflict` or
+`workspace_busy`. An app built against another package than its workspace
+runs answers `deploying`: the package deploys first, keeping the inputs
+people set, and the app goes live as the job completes. `appProblemText`, `appProblemLines` and `appProblemsText`
+print the problems; the `App*` types and limits are re-exported from
+`@elaraai/e3-cloud-types`.
+
+### Staging, releases and history
+
+A workspace's staging, another workspace of its repository that releases to
+it, **protects** it: its package and apps then change only by a release from
+its staging, or a rollback. A protected workspace refuses an app deploy or
+removal (`workspace_protected`, naming its staging) unless an admin forces it
+(`appDeploy`'s `force`, `appRemove`'s `{ force: true }`; anyone else asking is
+`forbidden`), and its history records each forced change.
+
+| Function | Answers |
+|---|---|
+| `addStaging(url, repo, live, { name, start, plan }, options)` | `AddStagingResponse` (owner or admin): `planned` or `added`, the plan (what it starts as: a copy of `live`, made or replacing a workspace of the name whole, or `as_is`; what a copy replaces; what it protects); `staging_conflict` when either is linked already, `not_found`, `workspace_busy` |
+| `stopStaging(url, repo, live, options)` | `StagingLink` (admins alone): the staging and the workspace it no longer protects; nothing is deleted |
+| `releaseWorkspace(url, repo, target, { from, carry, removeApps, plan }, options)` | `ReleaseResponse` (owner or admin; `from` must be the target's staging, else `not_staging`): `planned`, `refused` (its problems and checks in the plan; `nothing_to_release` when it would change nothing), `released` (its apps switched) or `releasing` (`{job, plan}`, the deploy job `appDeployWait` waits on); the plan's `undoes` names the changes forced onto the target since its last release, and each app's `stagedFor` the next e3's bundle it stages or clears |
+| `rollbackWorkspace(url, repo, ws, { to, plan }, options)` | the same, for an entry of the workspace's history: the one `to` names, or (none) the newest completed one that differs from what it runs |
+| `workspaceHistory(url, repo, ws, options, { limit?, before? })` | `WorkspaceHistoryPage`: entries newest first, and `next` |
+| `repositoryHistory(url, repo, options)` | `RepositoryHistory` (owner or admin): every workspace with a history, in brief, by name: its newest entry, its newest under way and its newest completed change (`WorkspaceHistorySummary`), in one request |
+| `workspaceHistoryEntry(url, repo, ws, id, options)` | `WorkspaceHistoryEntry` |
+| `getReleaseSettings(url, repo, ws, options)` | where a workspace releases to, when it is a staging |
+| `getRepositoryReleaseSettings(url, repo, options)` | `RepositoryReleaseSettings`: each staging, and the workspace it protects |
+
+A release throws `ApiError` with `not_found`, `not_staging`, `workspace_busy`
+(retry once the deploy, copy, removal or run that holds the target ends),
+`source_changed`, `app_conflict`, `entry_not_completed`, `entry_not_a_change`
+(a rollback to an entry that changed only a protection) or
+`package_deploy_unavailable`. `releaseProblemText` and
+`releasePlanRefusalLines` print a plan's problems; the `Release*` types and
+`RELEASE_CARRY_MAX` are re-exported from `@elaraai/e3-cloud-types`.
+
+## Error Handling
+
+All API functions throw on failure. Two error types are re-exported from `@elaraai/e3-api-client`:
+
+- **`ApiError`** — Application-level errors (e.g., `forbidden`, `not_found`, `user_not_found`)
+- **`AuthError`** — 401 Unauthorized (token expired or invalid)
+
+```typescript
+import { whoami, ApiError, AuthError } from '@elaraai/e3-cloud-client';
+
+try {
+  const me = await whoami(url, options);
+  console.log('User:', me.sub);
+} catch (error) {
+  if (error instanceof AuthError) {
+    console.error('Not authenticated');
+  } else if (error instanceof ApiError) {
+    console.error('Error:', error.code, error.message);
+  }
+}
+```
+
+## License
+
+[BSL 1.1](./LICENSE.md). Production use needs a commercial license from Elara
+AI Pty Ltd. Each release becomes AGPL-3.0 four years after it is released.

package/dist/src/admin-users.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type AdminUserList, type PersonList } from '@elaraai/e3-cloud-types';
+import { type RequestOptions } from '@elaraai/e3-api-client';
+/**
+ * List all deployment users (admin only), sorted by email.
+ */
+export declare function listAdminUsers(url: string, options: RequestOptions): Promise<AdminUserList>;
+/**
+ * Block a user's platform sign-in (admin only; never your own account).
+ *
+ * Takes effect at once: their next request is refused (`account_disabled`),
+ * with a token already issued too.
+ */
+export declare function disableUser(url: string, sub: string, options: RequestOptions): Promise<void>;
+/**
+ * Restore a user's platform sign-in (admin only).
+ */
+export declare function enableUser(url: string, sub: string, options: RequestOptions): Promise<void>;
+/**
+ * The people of the given subjects and emails, those the directory holds
+ * (admin): what a page needs to name who did something, never the whole
+ * directory. At most `PEOPLE_LOOKUP_MAX` subjects and emails together.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param keys - The subjects and emails to look up
+ * @param options - Request options including auth token
+ * @returns The people found
+ */
+export declare function lookupPeople(url: string, keys: {
+    subs?: readonly string[];
+    emails?: readonly string[];
+}, options: RequestOptions): Promise<PersonList>;
+//# sourceMappingURL=admin-users.d.ts.map

package/dist/src/admin-users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-users.d.ts","sourceRoot":"","sources":["../../src/admin-users.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,EAAqC,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACjH,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExE;;GAEG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAEjG;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAElG;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjG;AAID;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAM5J"}

package/dist/src/admin-users.js

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Deployment-level admin user API functions using BEAST2 format.
+ *
+ * One merged row per person: directory record, invitation state (with the
+ * identity provider's onboarding outcome), repo memberships and last seen. Disable/enable
+ * act on this platform only: the person's identity-provider account is
+ * unaffected.
+ */
+import { NullType } from '@elaraai/east';
+import { AdminUserListType, PersonListType } from '@elaraai/e3-cloud-types';
+import { get, post } from '@elaraai/e3-api-client';
+/**
+ * List all deployment users (admin only), sorted by email.
+ */
+export async function listAdminUsers(url, options) {
+    return get(url, '/admin/users', AdminUserListType, options);
+}
+/**
+ * Block a user's platform sign-in (admin only; never your own account).
+ *
+ * Takes effect at once: their next request is refused (`account_disabled`),
+ * with a token already issued too.
+ */
+export async function disableUser(url, sub, options) {
+    await post(url, `/admin/users/${encodeURIComponent(sub)}/disable`, null, NullType, NullType, options);
+}
+/**
+ * Restore a user's platform sign-in (admin only).
+ */
+export async function enableUser(url, sub, options) {
+    await post(url, `/admin/users/${encodeURIComponent(sub)}/enable`, null, NullType, NullType, options);
+}
+/**
+ * The people of the given subjects and emails, those the directory holds
+ * (admin): what a page needs to name who did something, never the whole
+ * directory. At most `PEOPLE_LOOKUP_MAX` subjects and emails together.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param keys - The subjects and emails to look up
+ * @param options - Request options including auth token
+ * @returns The people found
+ */
+export async function lookupPeople(url, keys, options) {
+    const query = new URLSearchParams();
+    for (const sub of keys.subs ?? [])
+        query.append('sub', sub);
+    for (const email of keys.emails ?? [])
+        query.append('email', email);
+    const text = query.toString();
+    return get(url, `/admin/people${text === '' ? '' : `?${text}`}`, PersonListType, options);
+}
+//# sourceMappingURL=admin-users.js.map

package/dist/src/admin-users.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-users.js","sourceRoot":"","sources":["../../src/admin-users.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAuC,MAAM,yBAAyB,CAAC;AACjH,OAAO,EAAE,GAAG,EAAE,IAAI,EAAuB,MAAM,wBAAwB,CAAC;AAExE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,OAAuB;IACvE,OAAO,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,GAAW,EAAE,OAAuB;IACjF,MAAM,IAAI,CAAC,GAAG,EAAE,gBAAgB,kBAAkB,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACxG,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW,EAAE,GAAW,EAAE,OAAuB;IAChF,MAAM,IAAI,CAAC,GAAG,EAAE,gBAAgB,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACvG,CAAC;AAID;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,IAA8D,EAAE,OAAuB;IACrI,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE;QAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE;QAAE,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC9B,OAAO,GAAG,CAAC,GAAG,EAAE,gBAAgB,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;AAC5F,CAAC"}

package/dist/src/apps.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type AdminAppPage, type AppRebuilds, type RepositoryApps, type AppDeployRequest, type AppDeployResponse, type AppList, type AppRemoved, type AppSource, type AppSummary, type AppVersionPage, type AppsDeployRequest } from '@elaraai/e3-cloud-types';
+import { type RequestOptions } from '@elaraai/e3-api-client';
+import { type WorkspaceDeployProgress, type WorkspaceDeployResult } from '@elaraai/e3-types';
+/** Which page of an app's versions to read. */
+export interface AppVersionsOptions {
+    /** The page's size (server default 20, at most 50) */
+    limit?: number;
+    /** The previous page's `next` */
+    cursor?: string;
+}
+/**
+ * A workspace's apps, each its current version.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param options - Request options including auth token
+ * @returns The apps, by name
+ */
+export declare function appList(url: string, repo: string, ws: string, options: RequestOptions): Promise<AppList>;
+/**
+ * An app: its current version, the hash of the one before, and any bundle
+ * staged for the platform's next e3.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param app - The app's name
+ * @param options - Request options including auth token
+ * @returns The app
+ * @throws {ApiError} `not_found` when the workspace has no app of the name
+ */
+export declare function appGet(url: string, repo: string, ws: string, app: string, options: RequestOptions): Promise<AppSummary>;
+/**
+ * A page of an app's kept versions, newest first (owner or admin).
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param app - The app's name
+ * @param options - Request options including auth token
+ * @param page - The page's size and the cursor
+ * @returns The page and the next page's cursor
+ */
+export declare function appVersions(url: string, repo: string, ws: string, app: string, options: RequestOptions, page?: AppVersionsOptions): Promise<AppVersionPage>;
+/**
+ * Uploads an app object (owner or admin): asks where its bytes go, then
+ * PUTs them there, to a URL that takes only bytes of their hash.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param app - The app's name
+ * @param bytes - The app object, as `@elaraai/e3-cloud-ui`'s `encodeAppObject` encodes it
+ * @param options - Request options including auth token
+ * @returns The source a deploy names: the upload, by its id
+ * @throws {Error} When the PUT is refused
+ */
+export declare function appUpload(url: string, repo: string, ws: string, app: string, bytes: Uint8Array, options: RequestOptions): Promise<AppSource>;
+/**
+ * A deploy as {@link appDeploy} takes it: the request, `force` unset unless
+ * asked (only an admin forces a deploy past a workspace's
+ * protection).
+ */
+export type AppDeployAsk = Omit<AppDeployRequest, 'force'> & {
+    readonly force?: boolean;
+};
+/** A deploy of several as {@link appsDeploy} takes it: `force` unset unless asked. */
+export type AppsDeployAsk = Omit<AppsDeployRequest, 'force'> & {
+    readonly force?: boolean;
+};
+/**
+ * Deploys an app (owner or admin): checked against the package it was
+ * built against; live at once when the workspace runs that package, or
+ * staged for the platform's next e3. A protected workspace, one with a
+ * staging, refuses it (`workspace_protected`) unless an admin forces it.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param app - The app's name
+ * @param request - Its object (an upload, or an object the repository holds), whether to stage it or only check it, and whether to force it
+ * @param options - Request options including auth token
+ * @returns `refused`, `checked`, `live` or `staged`
+ */
+export declare function appDeploy(url: string, repo: string, ws: string, app: string, request: AppDeployAsk, options: RequestOptions): Promise<AppDeployResponse>;
+/**
+ * Deploys several apps built against one package, together (owner or admin):
+ * each is checked with the others in place of their current versions, and
+ * they switch together or not at all.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param request - The apps, whether to stage them or only check them, and whether to force them
+ * @param options - Request options including auth token
+ * @returns `refused`, `checked`, `live` or `staged`
+ */
+export declare function appsDeploy(url: string, repo: string, ws: string, request: AppsDeployAsk, options: RequestOptions): Promise<AppDeployResponse>;
+/** How {@link appRemove} removes an app. */
+export interface AppRemoveOptions {
+    /**
+     * Remove it past its workspace's protection: admins
+     * only, recorded in the workspace's history as forced; without it a
+     * protected workspace refuses the removal (`workspace_protected`)
+     */
+    force?: boolean;
+}
+/**
+ * Removes an app (owner or admin): its current version and every version it
+ * keeps. A protected workspace, one with a staging, refuses it unless an
+ * admin forces it.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param app - The app's name
+ * @param options - Request options including auth token
+ * @param remove - Whether to force it past the workspace's protection
+ * @returns The app's name, and the users whose role names it, whose rows are left to an admin
+ */
+export declare function appRemove(url: string, repo: string, ws: string, app: string, options: RequestOptions, remove?: AppRemoveOptions): Promise<AppRemoved>;
+/** Which page of the deployment's apps to read. */
+export interface AdminAppListOptions {
+    /** The page's size (server default 50, at most 100) */
+    limit?: number;
+    /** The previous page's `next` */
+    cursor?: string;
+}
+/** How {@link appDeployWait} waits for a deploy job. */
+export interface AppDeployWaitOptions {
+    /** Called with the job's progress each time a poll finds it running */
+    onProgress?: (progress: WorkspaceDeployProgress) => void;
+    signal?: AbortSignal;
+    /**
+     * The request options for each poll, read afresh (a token refreshed as it
+     * expires, for a deploy that outlives it); absent, `options` throughout
+     */
+    refresh?: () => Promise<RequestOptions>;
+    /** How long to wait at most, in milliseconds, before giving up; absent, as long as the job runs */
+    deadlineMs?: number;
+}
+/**
+ * Waits for the deploy job an app deployed with its package started
+ * (`deploying`): polls e3's `GET …/workspaces/:ws/deploy/:id` until it
+ * ends. Its apps are live once it has completed.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param ws - Workspace name
+ * @param job - The job, as `deploying` names it
+ * @param options - Request options including auth token
+ * @param waitOptions - Its progress and cancellation
+ * @returns What the deploy decided for each record, index and input
+ * @throws {Error} When the deploy fails: its apps stay as they were
+ */
+export declare function appDeployWait(url: string, repo: string, ws: string, job: string, options: RequestOptions, waitOptions?: AppDeployWaitOptions): Promise<WorkspaceDeployResult>;
+/**
+ * The apps you can open across the repositories you belong to: every
+ * app of each repository you own, but a staging workspace's (the console
+ * reaches those by its switch), and the apps your business roles grant (a
+ * staging's too where a role names it), by repository,
+ * workspace and name, each its current version. The console's sidebar lists
+ * them; `myAccess` says which pages of each.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param options - Request options including auth token
+ * @returns Your apps
+ */
+export declare function myAppList(url: string, options: RequestOptions): Promise<AppList>;
+/**
+ * The apps that need a rebuild in the repositories you manage (every
+ * repository, for an admin; those you own, else): each built with another e3
+ * than the platform runs, with no bundle built with it staged, by
+ * repository, workspace and name; with the e3 the platform runs. A platform
+ * deploy is refused while one has no build for the e3 it deploys.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param options - Request options including auth token
+ * @returns The apps, and the platform's e3
+ */
+export declare function myAppRebuilds(url: string, options: RequestOptions): Promise<AppRebuilds>;
+/**
+ * A repository's apps in every workspace, by workspace and name, each its
+ * current version and any staged bundle, with the e3 the platform runs
+ * (owner or admin): an app built with another e3, with no bundle built with
+ * the platform's staged, needs a rebuild.
+ *
+ * @param url - Base URL of the e3 API server
+ * @param repo - Repository name
+ * @param options - Request options including auth token
+ * @returns Its apps, and the platform's e3
+ */
+export declare function repositoryAppList(url: string, repo: string, options: RequestOptions): Promise<RepositoryApps>;
+/**
+ * A page of the deployment's apps, by repository, workspace and name, each
+ * its current version and any staged bundle, with the e3 the platform runs
+ * (admin).
+ *
+ * @param url - Base URL of the e3 API server
+ * @param options - Request options including auth token
+ * @param page - The page's size and the cursor
+ * @returns The page, the next page's cursor, and the platform's e3
+ */
+export declare function adminAppList(url: string, options: RequestOptions, page?: AdminAppListOptions): Promise<AdminAppPage>;
+//# sourceMappingURL=apps.d.ts.map

package/dist/src/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/apps.ts"],"names":[],"mappings":"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"}