appframe-updater

Programmatic API for driving the Appframe updater system from Node or the browser. It wraps Appframe data handlers and procedures to check for, download, generate, deploy and apply updates across namespaces.

Purpose

• Provide a small, typed API on top of Appframe’s updater endpoints and procedures.

• Enable CI/CD flows and admin tools to automate update lifecycles (check → download → generate → deploy → apply).

• Work with the same Client type as @olenbetong/appframe-data for consistency and reuse of auth/host configuration.

High‑Level Concepts

• Namespace: Logical grouping of updates for an application or domain. Many operations can be scoped to a specific namespace by ID or name.

• Transactions: Individual update tasks generated per namespace before deployment. The package exposes helpers for listing transactions when needed.

• Procedures: Server-side procedures backing core actions:

  • generate: Create transactions for one or more namespaces.

  • deploy: Deploy (publish) generated transactions for a namespace or all.

  • apply: Apply deployed updates to the target environment.

• Client: All functions accept a Client from @olenbetong/appframe-data. Use the default client in the browser, or create/configure one in Node with a hostname and authentication.

Update Lifecycle (Typical Flow)

1. checkForUpdates: Ask the server which namespaces have updates available to download.

2. download: Download update packages for a namespace (optionally retrying on transient errors).

3. generate: Produce transactions for the namespace(s) you intend to deploy.

4. deploy: Deploy transactions for the selected namespace(s).

5. apply: Apply deployed updates. Can be run globally or scoped to a namespace.

You may run a subset of the steps depending on your environment and release process.

Key APIs

• checkForUpdates(client): Returns a list of { Namespace, Updates } with counts. See: ./checkForUpdates.md

• download(client, namespace): Downloads updates for a specific namespace name. See: ./download.md

• generate(client, namespace?): Generates transactions for one or all namespaces. See: ./generate.md

• deploy(client, namespace?): Deploys transactions for one or all namespaces. See: ./deploy.md

• apply(client, namespace?): Applies updates for one or all namespaces. See: ./apply.md

Utilities and data handlers

• createNamespaceDataHandler: Data handler for retrieving namespaces.

• getNamespace: Resolve a namespace by ID or name to its canonical record.

• dsTransactions exports: Helpers around transactions data access.

Usage

Install:

pnpm add @olenbetong/appframe-updater

Set up a client (Node example):

import { Client, setDefaultClient } from "@olenbetong/appframe-data";

const client = new Client("https://your.appframe.host");
setDefaultClient(client); // optional if you want a global default
// client.login(...) if required in your environment

Check and download updates for a namespace:

import { checkForUpdates, download } from "@olenbetong/appframe-updater";

const pending = await checkForUpdates(client);
for (const { Namespace, Updates } of pending) {
  if (Updates > 0 && Namespace === "MyNamespace") {
    await download(client, Namespace);
  }
}

Generate, deploy, then apply for a single namespace:

import { generate, deploy, apply } from "@olenbetong/appframe-updater";

await generate(client, "MyNamespace");
await deploy(client, "MyNamespace");
await apply(client, "MyNamespace");

Apply everything (no namespace filter):

import { apply } from "@olenbetong/appframe-updater";

await apply(client); // applies all deployed updates

Notes & Recommendations

• Idempotency: Server procedures are designed to be safe to run when nothing is pending; you’ll simply get no‑ops.

• Scope: Prefer scoping to a namespace in automated pipelines to avoid unintended cross‑app changes.

• Ordering: Typical order is generate → deploy → apply. Download is only required when your updater expects server-side packages.

• Errors: Functions throw on HTTP/procedure errors; wrap in try/catch in automation scripts and surface meaningful logs.

• Performance: generate without a namespace retrieves all namespaces. Consider providing a specific namespace ID/name in most flows.