GHL

GHL provides a small, tenant-isolated client for GHL products, prices, transactions and invoices. Alpha API: expect changes before stable. Published by BrightOps. Request alpha access at https://catalogue.brightops.io/#products; support: sundar@brightops.io.

Install and run

Configure the BrightOps registry with your host-owned license token, then install @wf/ghl@0.1.0-alpha.1. Node 22 or later is required. Copy examples/ghl.yaml, replace the allowed location, and run node examples/buyer.mjs /absolute/path/ghl.yaml YOUR_LOCATION_ID. The example reads a host credential; secrets never belong in YAML or browser code.

import { createGhlClient } from '@wf/ghl';
const client = createGhlClient('/app/config/ghl.yaml', {
  resolveCredential: (reference, locationId, signal) => hostSecrets.get(reference, locationId, signal),
});
try { console.log(await client.catalog('your-location')); }
finally { await client.close(); }

YAML is the sole settings interface. schemaVersion: 1, secretReference, and allowedLocations are sufficient. Maintained defaults: writes disabled, 30-second operation deadline, two read retries, 1,000-product catalog limit. Unknown settings and invalid bounds fail early. For multiple businesses use authorization: host and a required authorize(operation, locationId, signal) callback; resolve only that business’s credential. The host owns OAuth, refresh coordination, encrypted secret storage, authentication and persistence. Do not trust a URL location ID alone.

Public API

catalog(locationId, signal?) returns the complete count and {id,name} products, or an error if a bounded catalog cannot complete. read(locationId, resource, params?, signal?) accepts products, product, prices, price, transactions or invoice. Product prices require productId; a single price also requires priceId; invoices require invoiceId. Page reads accept limit (1–100) and offset. Each response is checked against the authorized business; price responses also match the product.

updateSellingPrice({locationId,productId,priceId,currency,amountMinor,expectedAmountMinor}, signal?) requires YAML allowWrites: true and host write authorization when supplied. It checks the current amount, preserves documented non-price fields, writes once, and verifies readback. Concurrent edits in GHL can still race between reads: the upstream API has no documented atomic compare-and-set. A network failure after a write returns WRITE_UNCERTAIN; refresh before retrying. No automatic write retries.

toMinorUnits(decimal, currency) converts exact nonnegative decimals to currency minor units. close() aborts and awaits in-flight work. Read retries honor cooldowns, with bounded response size, pagination, deadlines and cancellation. Error messages never include credential contents.

GHL permissions and limits

Product reads require products.readonly and products/prices.readonly. Selling-price writes require products/prices.write. Ledger reads require payments/transactions.readonly and invoices.readonly. Obtain the customer’s consent through their Marketplace installation; adding a scope to a config file cannot grant it.

The documented Update Price API does not expose native Cost Price writes. This alpha does not claim that capability. Store confirmed costs in your own ledger and keep historical allocations; never substitute selling prices or material estimates. Live product/write proof requires a suitably scoped GHL installation. Automated package tests use isolated GHL transport fixtures.

Cordis and MCP

The @wf/ghl/cordis plugin provides ghl using the same public client; the host provides ghlHost with runtime credential and authorization callbacks. Pass only configurationFile to plugin settings. See examples/cordis.yml.

@wf/ghl/mcp exports createMcpServer(configFile, runtime, authority). Current MCP protocol only: 2026-07-28. Tools: ghl_catalog, ghl_read, ghl_update_selling_price. Use the programmatic adapter to supply host credentials; the standalone command deliberately has no ambient credential fallback. MCP server YAML is documented in examples/mcp.yaml. Buyers own tool admission and user approval for customer-facing changes. No older protocol aliases are accepted.

Upgrade and rollback

Pin an exact alpha version. Preserve host YAML, credentials and data. Install the new immutable archive with its dependency lock; roll back both together. No automatic data migration or GHL mutation occurs at install. This software uses the bundled commercial LICENSE; alpha access is not a production SLA.