@elaraai/e3-cloud-types
v1.1.11
Published
The East types of e3 cloud's API, shared by its clients
Readme
@elaraai/e3-cloud-types
The East types of e3 cloud's API: what its requests and responses carry,
shared by its clients (@elaraai/e3-cloud-client, the e3-cloud CLI and the
web console).
Every type is an East type (StructType, VariantType, …), sent as BEAST2,
with its TypeScript type derived by ValueTypeOf. Its version is e3 cloud's
own, shared by every @elaraai/e3-cloud-* package and independent of east's
and e3's; each release is built with one release of east and e3.
Every time is an East DateTime (DateTimeType, a Date in TypeScript), never
text: print one with east's printFor(DateTimeType) (2026-11-02T08:01:52.123,
in UTC) and order them with compareFor(DateTimeType). Before 1.1.0 an
invitation's, a repository user's, a schedule's and Admin › Users' times were
ISO 8601 Strings: a client of 1.1.0 or later needs a platform of 1.1.0 or
later, and an older client an older platform.
Installation
npm install @elaraai/e3-cloud-typesIts peers are @elaraai/east and @elaraai/e3-types of the release it is
built with, which each version pins exactly (npm view
@elaraai/e3-cloud-types peerDependencies names them).
Usage
import {
// East type values (for serialization, type checking)
RepoRoleType,
RepoUserType,
AddUserRequestType,
WhoamiResponseType,
ComputeSizeType,
TaskConfigsType,
// TypeScript types (derived via ValueTypeOf)
type RepoRole,
type RepoUser,
type ComputeSize,
type TaskConfigs,
// Runtime utilities
parseRepoRole,
describeComputeSizes,
} from '@elaraai/e3-cloud-types';
import { variant, some } from '@elaraai/east';
// Parse a role from user input (throws if invalid)
const role = parseRepoRole('user', ['Rostering']);
// A repository user, as the API lists them
const user: RepoUser = {
userId: 'abc123-def456',
email: '[email protected]',
name: some('Alice Smith'),
role: variant('owner', null),
addedBy: 'abc123-def456',
addedAt: new Date(Date.UTC(2025, 0, 29, 10)),
};Types
RepoRoleType / RepoRole
Role a person can have on a repository (variant type):
.owner- builds and runs it: everything in it, its data directly through the API, its people and roles.user-{ roles }: holds business roles by name, which grant apps and pages; reaches only what those pages bind
parseRepoRole('owner' | 'user', roles?), serializeRepoRole, businessRolesOf(role), and ALL_APPS_ROLE ('All apps', every repository's built-in role: every app of its live workspaces, every page).
Business role types
BusinessRoleType-{ name, grants }: a repository's role, by the job people do (Rostering, Finance); its name 1–64 letters, digits, spaces and-_.&(), neverAll apps(businessRoleNameProblem,BUSINESS_ROLE_NAME_MAX)RoleGrantType-{ workspace, app, pages }: an app a role grantsRolePagesType-.all(every page, those a later version adds too) or.some([names])BusinessRoleListType- a repository's roles, by nameAppAccessType,MyAccessType- whatGET /api/me/accessanswers: each app the caller's roles grant ({ repo, workspace, app, pages }), in the repositories it is no owner ofRolePreviewType- what someone holding one role, and nothing else, gets: the apps their sidebar lists and what each grants
RepoUserType / RepoUser
A user entry in a repository's ACL:
userId- the user's subject ID (sub, immutable)email- User's email address (for display)name- Optional display name (OptionType)role- User's role on the repository (RepoRoleType)addedBy- userId of who added this entryaddedAt- when they were added (a DateTime)
RepoInvitationType is a person added who has not signed in yet: their email, the role they will get, and when they were invited.
AddUserRequestType / AddUserRequest
Request body for adding a person to a repository: their email and role. Someone who has not signed in yet is invited, and gets the role at their first sign-in.
WhoamiResponseType / WhoamiResponse
Response from /api/whoami: the caller's sub, email, name and whether they are an admin.
AuthzErrorType / AuthzError
Error response for authorization failures.
ScheduleType / Schedule
A workspace schedule for recurring dataflow execution:
repo- Repository nameworkspace- Workspace namecronExpression- Unix 5-field cron expressiontimezone- IANA timezone stringforceTasks- Task names to force (skip cache)enabled- Whether schedule is activedescription- Optional human-readable description (OptionType)createdBy- userId who created the schedulecreatedAt/updatedAt- when it was created and last changed (DateTimes)schedulerName- the schedule's name with the deployment's scheduler
ScheduleRequestType / ScheduleRequest
Request body for creating or updating a schedule.
ComputeSizeType / ComputeSize
Compute tier for task execution (variant type): .serverless, sized
automatically from the task's measured peak, or a container size, .small,
.medium, .large or .xlarge. CONTAINER_COMPUTE_SIZES and
SERVERLESS_COMPUTE say what each offers, and describeComputeSizes() says
it in a line per size:
serverless: a function sized from the task's measured peak (2 GB, 4 GB, 10 GB RAM; 15 min max)
small: container, 2 vCPU / 8 GB
medium: container, 4 vCPU / 16 GB
large: container, 8 vCPU / 32 GB
xlarge: container, 16 vCPU / 64 GBTaskTimeoutType / TaskTimeout
Custom timeout configuration for a task:
minutes- Timeout in minutes (TIMEOUT_MIN_MINUTEStoTIMEOUT_MAX_MINUTES: 1–43200)
ComputeConfigMapType / ComputeConfigMap
Dictionary of task name → ComputeSize.
TimeoutConfigMapType / TimeoutConfigMap
Dictionary of task name → TaskTimeout.
TaskConfigsType / TaskConfigs
Combined task configuration struct:
compute- ComputeConfigMaptimeout- TimeoutConfigMap
WorkspaceWidthType is a workspace's dataflow width: its own, if set, the deployment's default and the most it may be.
Feedback types
Notes users send about a part of a workspace's pages, kept per workspace and
numbered FB-<number> (feedbackId(n)); the routes are
/api/repos/:repo/workspaces/:ws/feedback/….
What a send carries, FeedbackSendRequestType / FeedbackSendRequest:
note- the text, 1–2,000 characters (FEEDBACK_NOTE_MAX_CHARS), not all spacespage-FeedbackPageType:url(location.href, ≤ 2,048),route(the route's pattern),title,viewportWidth,viewportHeight,devicePixelRatio,theme,version(the UI's build)part-FeedbackPartType:scope(.element|.page),label(as the hover Tag shows it),kind(.cloudwith the primitive's name |.east-uiwith thedata-slotor Chakra slot class),text(innerText, ≤ 2,000),path(a short CSS path),rectandclick(an Option; page coordinates)data-FeedbackDataType:task(an Option),datasets(path → hash of every dataset the view shows, ≤ 64)screenshot-FeedbackScreenshotRequestType:.image{ mediaType, width, height, bytes }(image/webporimage/jpeg, ≤ 1.5 MiB) |.omittedwith why
Every other text is at most 256 characters (FEEDBACK_SHORT_MAX_CHARS), and the
note and its context at most 16 KiB (FEEDBACK_NOTE_MAX_BYTES).
What the routes answer:
FeedbackSentType-{ id: 'FB-<n>', number }FeedbackNoteType/FeedbackNote- a note whole:number,status(FeedbackStatusType:.open|.closed),repo,workspace,note,sender(FeedbackSenderType:sub,email,name, from the verified token),createdAt,page,part,data,screenshot(FeedbackScreenshotType:.stored{ mediaType, width, height, size }|.omittedwith why)FeedbackSummaryType- a note in its sender's own list:number,status,note(its first 200 characters),truncated,part(its label),createdAtFeedbackListType- a page of the workspace's notes, whole:notes,next(the next page's cursor),counts(FeedbackCountsType:open,closed)FeedbackMineType- a page of the caller's own:notes(summaries),nextFeedbackSettingsType-{ enabled }, whether the workspace takes feedbackFeedbackScreenshotUrlType-{ url }, readable for 15 minutes
A page is 25 notes unless asked (FEEDBACK_PAGE_DEFAULT), at most 50
(FEEDBACK_PAGE_MAX); a full page has a cursor, which may lead to an empty
page.
And the rest
- Invitations and users:
InvitationType(a person invited by email, the grants they get at their first sign-in, and the identity provider's onboarding outcome where a deployment automates it),AdminUserType(Admin › Users: one row per person, with their memberships and last sign-in),PersonType(a person a page names, looked up by subject or email:GET /api/admin/people, at mostPEOPLE_LOOKUP_MAX). - Rack delegation:
DelegationPolicyType,DelegationRuleType,DelegationTargetType,RackRegistrationType,RackSecurityPolicyType,RackActivityEntryType;LEASE_MIN_AGENTandagentVersionAtLeast, the oldest rack agent a deployment leases work to. - Secrets:
SecretEntryType, a secret's name and when it was set (values are write-only and never answered). - Record history and backups:
RecordInfoType,RecordAuditPageType,RecordBackupInfoTypeand their listings. - Apps:
AppSummaryType,AppVersionType,AppDeployRequestType,AppDeployResponseType, andAppProblemTypewithappProblemText, why an app does not fit a package;RepositoryAppsType, a repository's apps in every workspace with the e3 release the platform runs, by which an app built with another and with no bundle for it staged needs a rebuild;AppRebuildsType, the apps that need one in the repositories a person manages, with the platform's e3. - A repository's settings:
RepositorySettingsType, every workspace'sWorkspaceSettingsType(its task configs, task and function delegations, width, feedback switch andWorkspaceLastRunType, its last run's summary) in one answer. - Releases and staging:
ReleasePlanType,ReleaseRequestType,WorkspaceHistoryEntryType,StagingPlanTypeand the rest of a release's plan, a workspace's history and its staging;WorkspaceHistorySummaryType(a workspace's history in brief: its newest entry, its newest under way and its newest completed change) andRepositoryHistoryType, every workspace's of a repository in one answer.
License
BSL 1.1. Production use needs a commercial license from Elara AI Pty Ltd. Each release becomes AGPL-3.0 four years after it is released.
