Agent Commerce bridge (Paperclip plugin)

Bridge UI for Agent Commerce next to Paperclip: company page at /commerce-bridge (not /commerce, which Paperclip may reserve for its own Commerce operator UI). Includes ping, create payment intent, automation (auto_settle_native_sol, custodial wallet secret, POST /settle), sidebar link “Commerce bridge”, dashboard widget, and worker data/actions.

Published as @avirajkhare00/agent-commerce-bridge on npm.

A — Local path install (dev)

Use this while iterating. The Paperclip server must see the same filesystem as your checkout.

1. Build artifacts (required)

The host loads dist/worker.js. Without a build, activation fails with Worker entrypoint not found.

cd /Users/avirajkhare/hack2/plugins/agent-commerce-bridge
pnpm install
pnpm build

Confirm:

test -f dist/worker.js && echo OK

2. Uninstall broken npm installs (if any)

If you previously installed @paperclipai/plugin-agent-commerce-bridge from npm and it had no dist/, remove it in Board → Settings → Plugins so it does not shadow this plugin.

3. Install by absolute path

Board → Settings → Plugins → Install plugin → paste the plugin root (directory that contains package.json and dist/):

/Users/avirajkhare/hack2/plugins/agent-commerce-bridge

Or API (adjust host/port and auth to your setup):

curl -sS -X POST 'http://127.0.0.1:3100/api/plugins/install' \
  -H 'Content-Type: application/json' \
  -d '{"packageName":"/Users/avirajkhare/hack2/plugins/agent-commerce-bridge","isLocalPath":true}'

4. After code changes

pnpm build

Then reload the plugin (disable/enable) or let the host pick up changes if it watches your path.

5. Instance config

In Plugins → this plugin → configuration, set at least:

• commerce_api_base_url — Commerce origin only, e.g. http://127.0.0.1:3210
• commerce_tenant_api_key — Bearer token for Commerce

B — Publish to npm (then install by name)

1. Switch off local tarball SDK (required once)

This repo was scaffolded with file:.paperclip-sdk/*.tgz for @paperclipai/plugin-sdk / @paperclipai/shared. npm consumers will not have those paths.

Before publish, edit package.json:

1. Remove the entire pnpm.overrides block (or replace overrides with semver only if you still need them).
2. Replace devDependencies entries that point at file:.paperclip-sdk/... with registry versions, for example:

"devDependencies": {
  "@paperclipai/plugin-sdk": "^1.0.0",
  "@paperclipai/shared": "^0.3.1",
  ...
}

3. Run pnpm install and pnpm build again.

The worker bundle inlines most of the SDK; keeping matching semver avoids drift with the Paperclip host.

2. Version and visibility

• Bump version in package.json.
• Set "private": false when you are ready to publish a scoped public package (or keep private and use a private registry).

3. What gets published

files is set to ["dist", "README.md"] so the tarball only ships built output (not src/ or .paperclip-sdk/).

prepack runs pnpm build before npm pack / npm publish so you do not ship an empty dist/.

4. Publish

pnpm build
npm whoami
npm publish --access public

(Use pnpm publish if you prefer; ensure OTP/registry login as required.)

5. Install in Paperclip by package name

Plugins → Install → @avirajkhare00/agent-commerce-bridge (or whatever name you published under).

Optional: publish under @paperclipai/…

To match an internal name like @paperclipai/plugin-agent-commerce-bridge:

1. Change name in package.json.
2. Align id in src/manifest.ts with your naming policy (stable across releases).
3. Publish; existing DB rows for the old plugin id may need a fresh install.

Development commands

pnpm install
pnpm dev            # watch worker + manifest + UI
pnpm dev:ui         # local UI preview (port 4177)
pnpm test
pnpm typecheck

Build options

• pnpm build — esbuild via @paperclipai/plugin-sdk/bundlers.
• pnpm build:rollup — rollup preset from the same package.