______   _    ____  ____ ___ _____ _____ ____ _____
 |__  /  / \  |  _ \|  _ \_ _|  ___| ____/ ___|_   _|
   / /  / _ \ | |_) | |_) | || |_  |  _| \___ \ | |
  / /_ / ___ \|  __/|  __/| ||  _| | |___ ___) || |
 /____/_/   \_\_|   |_|  |___|_|   |_____|____/ |_|
                                      n a n o  >_

Your manifests. Straight to Zapp. A tiny, zero-dependency Node.js CLI and CommonJS API. No Ruby. No extra baggage.

Install. Publish. Done.

npm install --save-dev @applicaster/zappifest-nano

export ZAPP_TOKEN='your-token'
npx zappifest-nano publish --manifest manifests/ios.json

Requires Node.js 22+. Keep the token in your environment, not in command arguments or source control. The executable is zappifest-nano, not zappifest.

Before the first npm release, run npm pack in this repo and install the resulting .tgz in your project instead.

CLI commands

publish

# Single manifest
npx zappifest-nano publish --manifest manifests/ios.json

# Directory
npx zappifest-nano publish --directory manifests

# Multiple manifests
npx zappifest-nano publish -m manifests/ios.json -m manifests/android.json

# New plugin (owner account required)
npx zappifest-nano publish -m manifest.json --new --account ACCOUNT

# Replace a published version (version-record ID, not parent-plugin ID)
npx zappifest-nano publish manifest.json --plugin-id VERSION_ID

| Option | Description | | --- | --- | | --manifest, -m <path> | Manifest file; repeat to include more files. | | --directory, -d <path> | Folder of JSON manifests; repeat or combine with -m. | | --dry-run | Validate and preview locally without a token, network requests, or writes. | | --new | Create a parent plugin; requires --account and creation metadata. | | --plugin-id <id> | Overwrite one existing version record, after a diff and confirmation. | | --yes | Approve overwrite without prompting; required in noninteractive runs. | | --account <id> | Optional for existing plugins; validates developer access and owner. | | --plugin-guide, --plugin-about <path> | Markdown files for parent metadata, not embedded manifest. | | --access-token <token> | Explicit auth; prefer ZAPP_TOKEN to keep tokens out of process arguments. | | --base-url, --accounts-url <url> | Override the Admin / Accounts API endpoints. | | --help, -h | Show usage and options. | | --version, -v | Show the installed package version. |

Scans direct regular .json files in filename order, without recursion. Objects with any identifier, platform, or manifest_version key are manifest candidates and must pass full validation. Valid unrelated JSON is reported and skipped; malformed JSON or incomplete candidates stop everything before network access. Empty/no-manifest folders fail. Nothing executes local JavaScript.

Repeat or combine --manifest / -m and --directory / -d; overlapping paths are uploaded once. Manifests with the same identifier upload concurrently; different identifiers run sequentially.

Manifest format

Required: identifier, platform, and manifest_version as non-empty strings. All other fields pass through unchanged.

{
  "identifier": "my_plugin",
  "platform": "ios",
  "manifest_version": "1.0.0",
  "targets": ["mobile"],
  "ui_frameworks": ["native"]
}

Account discovery

npx zappifest-nano accounts
npx zappifest-nano plugins --account ACCOUNT

Legacy names show_accounts / get_account_plugins are also supported. Output distinguishes parent IDs from version IDs returned by the server.

JavaScript API

const { publish } = require("@applicaster/zappifest-nano");

publish({ manifestPaths: ["manifests/ios.json"], log: console.log })
  .then(console.log)
  .catch(console.error);

| Export | Inputs / capabilities | | --- | --- | | publish(options) | manifestPaths: [], manifestDirectories: [], or both. | | publishManifests(options) | manifests: [] containing objects or JSON strings. | | createClient(options) | Plugin lookup/create/update, version uploads, account discovery, and client-scoped mappings. |

Options include token, baseUrl, accountsUrl, and onWarning; publishing also accepts dryRun, log, account, createNew, versionId, confirmOverwrite, and overwriteConfirmed. publish reads guidePath / aboutPath; publishManifests accepts Markdown text as guide / about. Authentication defaults to ZAPP_TOKEN; endpoint overrides also use ZAPP_URL / ZAPP_ACCOUNTS_URL. See publishing/API details for examples. Both publishing functions resolve to { dryRun, manifestCount, identifierCount, uploaded } or reject. Direct client upload calls return a native Response for you to consume. Progress logging is opt-in; mapping warnings default to console.warn.

Notes

ZAPP_URL defaults to https://zapp.applicaster.com/api/v1/admin; use HTTPS with real credentials. Requests time out after 30 seconds and never follow redirects. Existing-plugin publishing needs no account and makes no Accounts API calls unless --account is supplied. Parent metadata sync changes supplied fields only, once per identifier; it never transfers ownership or replaces a whitelist.

Mappings load dynamically with warned built-in fallbacks; unknown names fail before uploads. Dry-run cannot validate live IDs or mappings. Uploads are not transactional: failures wait for in-flight uploads and stop later groups, but successful versions remain published. Inspect Zapp before retrying. Overwrite is limited to one manifest with the same identifier, platform, and version. The diff redacts credential-like values; server authorization still applies.

Development

npm test              # Unit, CLI, local API, and real packed-install checks
npm run test:pack     # Packed tarball + offline install smoke check only
npm pack --dry-run    # Inspect exactly what ships; does not publish

No runtime dependencies. Agent guide | Maintainer releases. CircleCI releases main/master using Conventional Commits: fix = patch, feat = minor, breaking change = major.