Orbito Orders managment

@orbito/omm (1.1.0)

Published 2026-10-13 12:54:58 +02:00 by wiktor

Installation

@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/
npm install @orbito/omm@1.1.0
"@orbito/omm": "1.1.0"

About this package

OrbitoModulesManager — CLI to pack, publish and test Orbito modules (modules.orbito.pl, Orbito Core)

OMM — OrbitoModulesManager

CLI for Orbito modules:

  • registry (modules.orbito.pl) — pack and publish modules, the npm publish of Orbito modules;
  • Orbito Core (v2.orbito.pl) — install a module version in your test company, read its logs and problems, call its methods and update it — the build/test loop without the web panel.

The package identity (module code and version) comes only from module.json in the module directory. The module card in the registry is created by omm init (or in the developer panel) — omm publish never creates it.

Installation

npm config set @orbito:registry https://git.kozminski.net.pl/api/packages/orbito/npm/   # once per machine
npm i -g @orbito/omm

@orbito/omm and @orbito/api-lib are not on npmjs.org: they live in the Orbito npm registry, which allows anonymous downloads (no token) but needs the @orbito scope mapped in ~/.npmrc:

@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/

Without this line npm i -g @orbito/omm and npm install in a module fail with 404.

Requires Node.js >= 18.13. To work on the CLI itself: npm install && npm link in the repo directory.

Publishing a new CLI version: bump version in package.json and run npm publish (the registry is set in publishConfig).

Usage

New module (omm init)

omm init "Hello"                          # create the module card in the registry + scaffold ./hello
omm init "Hello" --description "Greets people" --dir my-hello
omm init "Hello" --code acme/hello        # the card already exists: scaffold only, no registry call

omm init <name> [--dir <dir>] [--code <org/name>] [--description <text>] [-r, --registry <url>]

  • <name> is the display name of the module card.
  • Without --code the command creates the module card in the registry (POST /developer/modules, needs omm login); the registry assigns the module code <username>/<slug of the name>. With --code the card must already exist and the registry is not called.
  • --dir defaults to the name part of the code (acme/hello → hello). The directory must not exist or must be empty.
  • The module is created from the template built into omm (the same code as the hello-module example in the docs): module.json, package.json, index.js, pages/hello.yaml and .gitignore, with the module code put into every file and --description into package.json. npm install is not run.
  • --json prints { code, dir, files, cardCreated }.

Next: cd <dir> && npm install, then follow the build loop: https://orbito.pl/docs/agents/build-loop.html

Registry

omm login                      # password login; creates and saves a publish token
omm login --token omm_abc...   # CI: use an existing publish token
omm whoami                     # who is logged in
omm logout                     # revoke the token and remove it from the config

omm pack --dry-run             # show what goes into the package
omm pack                       # build the ZIP locally (no upload)

omm publish                    # pack + upload a DRAFT + wait for the Docker build
omm publish --release          # as above + publish in the registry (draft → published)
omm publish --no-wait          # upload a draft and do not wait for the build
omm publish --changelog "..."  # with release notes

omm secrets list               # module secrets with their status (never values)
omm secrets set ALLEGRO_CLIENT_ID     # set a value (hidden prompt)
omm secrets unset ALLEGRO_CLIENT_ID   # remove a value

By default publish uploads a draft — for testing. Publishing in the registry (visible to all companies) requires an explicit --release.

The version of a new publish is bumped by editing version in module.json (it must be a semver higher than the last published version). A draft of the same version can be uploaded again — it overwrites the previous draft.

Orbito Core (test loop)

omm login --core               # e-mail + password of your Orbito account (JWT, 48 h)
omm login --core http://localhost:3003   # another core
omm login --core --token <jwt> # CI: use an existing core JWT
omm whoami --core              # account and working company
omm logout --core              # remove the core session from the config

omm company list               # your companies (* = working company)
omm company use <id>           # set the working company (id or list number)
omm company use                # choose interactively
omm company dev-token          # required once per company before installing your drafts

omm install                    # install the version from module.json (+ dependencies)
omm install --name "Shop B"    # a second instance of a non-singleton module
omm instances                  # instances of the module in the company
omm logs                       # module logs of today
omm logs --since 2026-10-13T10:00:00Z
omm logs --day 2026-10-12
omm logs --container           # Docker stdout/stderr of the module container
omm problems --status waiting  # problems reported by the module
omm call getOrders --params '{"limit": 5}'   # call a module method, print its result
omm update                     # update the instance to the version from module.json
                               # (same version: reload the container with a fresh image)

A typical loop: omm publish (draft) → omm company dev-token (once per company) → omm install → omm logs / omm problems / omm call → fix → omm publish (overwrites the draft) → omm update (reload) → … → omm publish --release. The version does not have to be bumped while you iterate on a draft.

  • The module code (and, for install/update, the version) is read from module.json in the current directory (-C <dir> for another one). instances, logs, problems and call also accept --module <org/name>.
  • update, logs and call act on the only active instance of the module in the working company. With more instances the command fails and lists their ids — choose one with --instance <id>.
  • install always installs missing dependencies too (withDependencies).
  • update compares the instance version with module.json. A different version updates the instance (POST /m/i/:id/update); the same version reloads it instead (POST /m/i/:id/reload): the container is stopped and its next start pulls the image again, so an overwritten draft takes effect. --json prints the core response plus "action": "update" or "action": "reload".
  • call runs the method with the permissions of the logged-in user; the core wraps the result in a one-element array — omm prints the element itself.
  • company dev-token sets the company dev-token to your developer token from the registry. It is required before the first install of a draft: the registry hands out draft images only to companies holding the author's token, so without it install and update of a draft fail with 404 (omm then suggests omm company dev-token, in --json as hint). It also makes the company marketplace show your draft versions. Published versions do not need it. The token is saved by password omm login (the registry only hands it out for a password session); after omm login --token pass it explicitly: omm company dev-token <uuid> (developer panel).
  • The core JWT is valid for 48 h and is refreshed automatically before a core command when less than 24 h are left. An expired session ends with an error asking for omm login --core.
  • Every core command accepts --core <url> and (except company list/use) --company <id>.

Output for scripts and AI agents (--json)

--json (anywhere on the command line) prints only the result as JSON on stdout; progress messages are suppressed. Errors go to stderr as {"error": "...", "status": 404} (status is the HTTP status or null, plus code/details when the server sends them and hint when omm knows the next step) and the exit code is 1. Commands never read stdin except the interactive ones: login without --token, company use without an argument and secrets set without OMM_SECRET_VALUE.

omm instances --json
omm call ping --json

Update notices and omm doctor

Once a day omm checks the latest @orbito/omm and @orbito/api-lib in the Orbito npm registry and the current agent skill (https://orbito.pl/docs/skill/version.json). The check starts together with the command and its result is printed after it (also after an error), always on stderr — stdout stays the clean command result:

! omm 1.1.0 is available (you have 1.0.1) — npm i -g @orbito/omm (https://orbito.pl/docs/agents/changelog.html)

With --json it is one line on stderr: {"notices":[{"kind":"omm|sdk|skill","message":"...","fix":"...","url":"..."}]}. Notices:

  • omm — a newer omm; fix npm i -g @orbito/omm, link to the changelog;
  • sdk — only in a module directory (module.json): the lowest version of the @orbito/api-lib range in package.json (^x.y.z, ~x.y.z, x.y.z, >=x.y.z) is older than the latest; fix npm i @orbito/api-lib@latest;
  • skill — a local orbito-modules/SKILL.md of Claude Code, Codex or OpenCode (user: ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills; project: .claude/skills, .codex/skills, .opencode/skills in the current directory) differs from the published one; fix: the installer curl -fsSL https://orbito.pl/docs/skill/install.sh | sh (-s -- --project for project copies).

The result is cached for 24 h in the config (updateCheck); each request has a 3 s timeout and network errors are silent (the previous result stays). OMM_NO_UPDATE_CHECK=1 turns the automatic check off (CI).

omm doctor checks the whole setup at once and always fetches fresh versions (also with OMM_NO_UPDATE_CHECK). Checks (ok / warn / fail, with a fix command): node (engines), omm (vs latest), npm-scope (npm config get @orbito:registry), registry-login (token + whoami, saved developer token), core-login, company, module (manifest, package.json with @orbito/api-lib, SDK vs latest) and skill:<agent> per agent with the skill installed. The exit code is 1 only when a check fails.

omm doctor          # table + fix lines
omm doctor --json   # { "checks": [{ "name", "status", "message", "fix"? }], "notices": [...] }

Configuration

  • ~/.config/omm/config.json — publish token per registry (registries) and session per core (cores[url] = { token, expiresAt, email, companyId }, core = last used core), last update check (updateCheck, cached 24 h).
  • OMM_TOKEN — publish token from env (overrides the config; for CI).
  • OMM_REGISTRY / --registry — registry API URL (default https://modules.orbito.pl/api).
  • OMM_CORE / --core <url> — core API URL (default: last used, then https://v2.orbito.pl/api).
  • OMM_CORE_TOKEN — core JWT from env (overrides the config, not refreshed).
  • OMM_COMPANY / --company <id> — working company (overrides omm company use).
  • OMM_SECRET_VALUE — value for omm secrets set without a prompt (CI).
  • OMM_NO_UPDATE_CHECK=1 — no automatic update check (CI); omm doctor still checks.
  • OMM_PACKAGES_REGISTRY — npm registry of the @orbito packages (default https://git.kozminski.net.pl/api/packages/orbito/npm/): source of the latest versions and the value omm doctor expects in @orbito:registry.

What goes into the package

If module.json has a files field (array of paths) — only the listed files and directories (module.json is always included). Without files — the whole module directory except: node_modules/, .git/, .env*, .npmrc, *.zip, make-zip.sh, editor files.

.npmrc is excluded by default (secrets in the package). If the module's Docker build needs private npm packages, add --include-npmrc deliberately.

Module secrets (omm secrets)

App keys (e.g. a marketplace client ID/secret) should not live in the module code. The registry stores the values — encrypted, globally per module code (not per version or company). The core fetches them when a module container starts and passes them as environment variables.

The module declares its secrets in module.json (without values):

{
    "name": "core/allegro",
    "version": "1.2.0",
    "secrets": [
        { "name": "ALLEGRO_CLIENT_ID", "description": "Allegro app client ID (production)" },
        { "name": "ALLEGRO_CLIENT_SECRET" }
    ]
}

Name: ^[A-Z][A-Z0-9_]*$, max 64 characters, no ORBITO_ prefix (reserved for the core), no duplicates; description is optional, max 200 characters.

omm secrets list                                  # module code from ./module.json
omm secrets list --module core/allegro            # or the given one
omm secrets set ALLEGRO_CLIENT_SECRET             # value from a hidden prompt
OMM_SECRET_VALUE=... omm secrets set ALLEGRO_CLIENT_SECRET   # CI, no prompt
omm secrets unset ALLEGRO_CLIENT_SECRET
  • list shows secrets declared in the latest version plus stored ones, with status set / missing value / undeclared — never the values.
  • set also works for a name that is not declared yet (values can be set before the first publish). An empty value is an error.
  • A new value reaches containers on their next start — no new module version needed.
  • Publishing is not blocked by missing values — omm publish --release prints a ⚠ warning for every declared secret without a value.

How publishing works

  1. POST /developer/publish — ZIP upload; the server reads module.json, checks the module card owner and semver, and queues the Docker image build. A draft of the same version is overwritten (retry without bumping the version); published versions are immutable.
  2. GET /developer/publish/:imageId — the CLI polls the build status.
  3. POST /developer/publish/:imageId/finalize — only with --release: publishing (draft → published); the previously published version becomes deprecated. Server warnings (warnings, e.g. a secret without a value) are printed as ⚠.

Authorization: Authorization: Bearer omm_... header (publish token, managed in the developer panel or by omm login/omm logout).

Orbito Core endpoints used

Command Endpoint
login --core POST /auth/signin, GET /users/me
(automatic refresh) POST /auth/refresh
company list / company use GET /users/me
company dev-token PUT /companies/:id/dev-token
install POST /m/:moduleCode/enable (org_name, withDependencies: true)
update POST /m/i/:id/update; same version: POST /m/i/:id/reload
instances GET /m/instances
logs GET /m/i/:id/logs (forDay, since), --container: GET /m/i/:id/container-logs
problems GET /problems?moduleCode=
call POST /m/i/:id/api/:method

Requests carry Authorization: Bearer <jwt> and the working company in x-company-id.

Dependencies

Dependencies

ID Version
commander ^12.1.0
yazl ^2.5.1
Details
npm
2026-10-13 12:54:58 +02:00
7
UNLICENSED
38 KiB
Assets (1)
omm-1.1.0.tgz 38 KiB
Versions (15) View all
2.2.0 2026-10-27
2.1.3 2026-10-27
2.1.2 2026-10-25
2.1.1 2026-10-25
2.1.0 2026-10-16