@lssm/example.openbanking-powens 0.0.0-canary-20251217062139 → 0.0.0-canary-20251217072406

package/dist/integrations/providers-impls/dist/impls/powens-client.js

@@ -1 +1,171 @@
-import{URL as e}from"node:url";const t={sandbox:`https://api-sandbox.powens.com/v2`,production:`https://api.powens.com/v2`};var n=class extends Error{status;code;requestId;response;constructor(e,t,n,r,i){super(e),this.name=`PowensClientError`,this.status=t,this.code=n,this.requestId=r,this.response=i}},r=class{clientId;clientSecret;apiKey;fetchImpl;logger;defaultTimeoutMs;token;baseUrl;constructor(e){this.clientId=e.clientId,this.clientSecret=e.clientSecret,this.apiKey=e.apiKey,this.fetchImpl=e.fetchImpl??fetch,this.logger=e.logger,this.defaultTimeoutMs=e.defaultTimeoutMs??15e3,this.baseUrl=e.baseUrl??t[e.environment]??t.production}async listAccounts(e){let t={cursor:e.cursor,limit:e.limit,include_balances:e.includeBalances,institution_uuid:e.institutionUuid};return await this.request({method:`GET`,path:`/users/${encodeURIComponent(e.userUuid)}/accounts`,searchParams:t})}async getAccount(e){return this.request({method:`GET`,path:`/accounts/${encodeURIComponent(e)}`})}async listTransactions(e){let t={cursor:e.cursor,limit:e.limit,from:e.from,to:e.to,include_pending:e.includePending};return this.request({method:`GET`,path:`/accounts/${encodeURIComponent(e.accountUuid)}/transactions`,searchParams:t})}async getBalances(e){return this.request({method:`GET`,path:`/accounts/${encodeURIComponent(e)}/balances`})}async getConnectionStatus(e){return this.request({method:`GET`,path:`/connections/${encodeURIComponent(e)}`})}async request(t){let r=new e(t.path,this.baseUrl);if(t.searchParams)for(let[e,n]of Object.entries(t.searchParams))n!=null&&r.searchParams.set(e,String(n));let i={Accept:`application/json`,"Content-Type":`application/json`,...t.headers};this.apiKey&&(i[`x-api-key`]=this.apiKey),t.skipAuth||(i.Authorization=`Bearer ${await this.ensureAccessToken()}`);let a=new AbortController,o=setTimeout(()=>a.abort(),t.timeoutMs??this.defaultTimeoutMs);try{let e=await this.fetchImpl(r,{method:t.method,headers:i,body:t.body?JSON.stringify(t.body):void 0,signal:a.signal}),o=e.headers.get(`x-request-id`)??void 0;if(!e.ok){let t;try{t=await e.json()}catch{}let r=typeof t==`object`&&t?t:void 0,i=typeof r?.message==`string`?r.message:`Powens API request failed with status ${e.status}`,a=typeof r?.code==`string`?r.code:void 0;throw new n(i,e.status,a,o,t)}if(e.status===204)return;try{return await e.json()}catch(t){throw this.logger?.error?.(`[PowensClient] Failed to parse JSON response`,t),new n(`Failed to parse Powens response payload as JSON`,e.status,void 0,o)}}catch(e){throw e instanceof n?e:e.name===`AbortError`?new n(`Powens API request timed out after ${t.timeoutMs??this.defaultTimeoutMs}ms`,408):(this.logger?.error?.(`[PowensClient] Request failed`,e),new n(e.message??`Powens API request failed`,500))}finally{clearTimeout(o)}}async ensureAccessToken(){return this.token&&Date.now()<this.token.expiresAt-5e3||(this.token=await this.fetchAccessToken()),this.token.accessToken}async fetchAccessToken(){let t=new e(`/oauth/token`,this.baseUrl),r=Buffer.from(`${this.clientId}:${this.clientSecret}`,`utf-8`).toString(`base64`),i=await this.fetchImpl(t,{method:`POST`,headers:{Authorization:`Basic ${r}`,"Content-Type":`application/x-www-form-urlencoded`,Accept:`application/json`},body:new URLSearchParams({grant_type:`client_credentials`}).toString()});if(!i.ok){let e;try{e=await i.json()}catch{}let t=typeof e==`object`&&e?e:void 0;throw new n(typeof t?.error_description==`string`?t.error_description:`Failed to obtain Powens access token`,i.status,void 0,void 0,e)}let a=await i.json(),o=Date.now()+a.expires_in*1e3;return this.logger?.debug?.(`[PowensClient] Received access token`,{expiresIn:a.expires_in}),{accessToken:a.access_token,expiresAt:o,scope:a.scope}}};export{n,r};
+import { URL } from "node:url";
+
+//#region ../../integrations/providers-impls/dist/impls/powens-client.js
+const POWENS_BASE_URL = {
+	sandbox: "https://api-sandbox.powens.com/v2",
+	production: "https://api.powens.com/v2"
+};
+var PowensClientError = class extends Error {
+	status;
+	code;
+	requestId;
+	response;
+	constructor(message, status, code, requestId, response) {
+		super(message);
+		this.name = "PowensClientError";
+		this.status = status;
+		this.code = code;
+		this.requestId = requestId;
+		this.response = response;
+	}
+};
+var PowensClient = class {
+	clientId;
+	clientSecret;
+	apiKey;
+	fetchImpl;
+	logger;
+	defaultTimeoutMs;
+	token;
+	baseUrl;
+	constructor(options) {
+		this.clientId = options.clientId;
+		this.clientSecret = options.clientSecret;
+		this.apiKey = options.apiKey;
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.logger = options.logger;
+		this.defaultTimeoutMs = options.defaultTimeoutMs ?? 15e3;
+		this.baseUrl = options.baseUrl ?? POWENS_BASE_URL[options.environment] ?? POWENS_BASE_URL.production;
+	}
+	async listAccounts(params) {
+		const searchParams = {
+			cursor: params.cursor,
+			limit: params.limit,
+			include_balances: params.includeBalances,
+			institution_uuid: params.institutionUuid
+		};
+		return await this.request({
+			method: "GET",
+			path: `/users/${encodeURIComponent(params.userUuid)}/accounts`,
+			searchParams
+		});
+	}
+	async getAccount(accountUuid) {
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountUuid)}`
+		});
+	}
+	async listTransactions(params) {
+		const searchParams = {
+			cursor: params.cursor,
+			limit: params.limit,
+			from: params.from,
+			to: params.to,
+			include_pending: params.includePending
+		};
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(params.accountUuid)}/transactions`,
+			searchParams
+		});
+	}
+	async getBalances(accountUuid) {
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountUuid)}/balances`
+		});
+	}
+	async getConnectionStatus(connectionUuid) {
+		return this.request({
+			method: "GET",
+			path: `/connections/${encodeURIComponent(connectionUuid)}`
+		});
+	}
+	async request(options) {
+		const url = new URL(options.path, this.baseUrl);
+		if (options.searchParams) for (const [key, value] of Object.entries(options.searchParams)) {
+			if (value === void 0 || value === null) continue;
+			url.searchParams.set(key, String(value));
+		}
+		const headers = {
+			Accept: "application/json",
+			"Content-Type": "application/json",
+			...options.headers
+		};
+		if (this.apiKey) headers["x-api-key"] = this.apiKey;
+		if (!options.skipAuth) headers.Authorization = `Bearer ${await this.ensureAccessToken()}`;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? this.defaultTimeoutMs);
+		try {
+			const response = await this.fetchImpl(url, {
+				method: options.method,
+				headers,
+				body: options.body ? JSON.stringify(options.body) : void 0,
+				signal: controller.signal
+			});
+			const requestId = response.headers.get("x-request-id") ?? void 0;
+			if (!response.ok) {
+				let errorBody;
+				try {
+					errorBody = await response.json();
+				} catch {}
+				const errorObject = typeof errorBody === "object" && errorBody !== null ? errorBody : void 0;
+				const message = typeof errorObject?.message === "string" ? errorObject.message : `Powens API request failed with status ${response.status}`;
+				const code = typeof errorObject?.code === "string" ? errorObject.code : void 0;
+				throw new PowensClientError(message, response.status, code, requestId, errorBody);
+			}
+			if (response.status === 204) return;
+			try {
+				return await response.json();
+			} catch (error) {
+				this.logger?.error?.("[PowensClient] Failed to parse JSON response", error);
+				throw new PowensClientError("Failed to parse Powens response payload as JSON", response.status, void 0, requestId);
+			}
+		} catch (error) {
+			if (error instanceof PowensClientError) throw error;
+			if (error.name === "AbortError") throw new PowensClientError(`Powens API request timed out after ${options.timeoutMs ?? this.defaultTimeoutMs}ms`, 408);
+			this.logger?.error?.("[PowensClient] Request failed", error);
+			throw new PowensClientError(error.message ?? "Powens API request failed", 500);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	async ensureAccessToken() {
+		if (this.token && Date.now() < this.token.expiresAt - 5e3) return this.token.accessToken;
+		this.token = await this.fetchAccessToken();
+		return this.token.accessToken;
+	}
+	async fetchAccessToken() {
+		const url = new URL("/oauth/token", this.baseUrl);
+		const basicAuth = Buffer.from(`${this.clientId}:${this.clientSecret}`, "utf-8").toString("base64");
+		const response = await this.fetchImpl(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Basic ${basicAuth}`,
+				"Content-Type": "application/x-www-form-urlencoded",
+				Accept: "application/json"
+			},
+			body: new URLSearchParams({ grant_type: "client_credentials" }).toString()
+		});
+		if (!response.ok) {
+			let errorBody;
+			try {
+				errorBody = await response.json();
+			} catch {}
+			const errorObject = typeof errorBody === "object" && errorBody !== null ? errorBody : void 0;
+			throw new PowensClientError(typeof errorObject?.error_description === "string" ? errorObject.error_description : "Failed to obtain Powens access token", response.status, void 0, void 0, errorBody);
+		}
+		const payload = await response.json();
+		const expiresAt = Date.now() + payload.expires_in * 1e3;
+		this.logger?.debug?.("[PowensClient] Received access token", { expiresIn: payload.expires_in });
+		return {
+			accessToken: payload.access_token,
+			expiresAt,
+			scope: payload.scope
+		};
+	}
+};
+
+//#endregion
+export { PowensClient, PowensClientError };

package/dist/integrations/providers-impls/dist/impls/powens-openbanking.js

@@ -1 +1,218 @@
-import{n as e,r as t}from"./powens-client.js";var n=class{client;logger;constructor(e){this.client=new t(e),this.logger=e.logger}async listAccounts(t){if(!t.userId)throw new e(`Powens account listing requires the upstream userId mapped to Powens user UUID.`,400);let n=this.toContext(t.tenantId,t.connectionId);try{let e=await this.client.listAccounts({userUuid:t.userId,cursor:t.cursor,limit:t.pageSize,includeBalances:t.includeBalances,institutionUuid:t.institutionId});return{accounts:e.accounts.map(e=>this.mapAccount(e,n)),nextCursor:e.pagination?.nextCursor,hasMore:e.pagination?.hasMore}}catch(e){this.handleError(`listAccounts`,e)}}async getAccountDetails(e){let t=this.toContext(e.tenantId,e.connectionId);try{let n=await this.client.getAccount(e.accountId);return this.mapAccountDetails(n,t)}catch(e){this.handleError(`getAccountDetails`,e)}}async listTransactions(e){let t=this.toContext(e.tenantId,e.connectionId);try{let n=await this.client.listTransactions({accountUuid:e.accountId,cursor:e.cursor,limit:e.pageSize,from:e.from,to:e.to,includePending:e.includePending});return{transactions:n.transactions.map(e=>this.mapTransaction(e,t)),nextCursor:n.pagination?.nextCursor,hasMore:n.pagination?.hasMore}}catch(e){this.handleError(`listTransactions`,e)}}async getBalances(e){let t=this.toContext(e.tenantId,e.connectionId);try{return(await this.client.getBalances(e.accountId)).filter(t=>e.balanceTypes?.length?e.balanceTypes.includes(t.type):!0).map(e=>this.mapBalance(e,t))}catch(e){this.handleError(`getBalances`,e)}}async getConnectionStatus(e){try{let t=await this.client.getConnectionStatus(e.connectionId);return{connectionId:e.connectionId,tenantId:e.tenantId,status:this.mapConnectionStatus(t.status),lastCheckedAt:t.lastAttemptAt,errorCode:t.errorCode,errorMessage:t.errorMessage,details:t.metadata}}catch(e){this.handleError(`getConnectionStatus`,e)}}mapAccount(e,t){return{id:e.uuid,externalId:e.reference??e.uuid,tenantId:t.tenantId,connectionId:t.connectionId,userId:e.userUuid,displayName:e.name,institutionId:e.institution.id,institutionName:e.institution.name,institutionLogoUrl:e.institution.logoUrl,accountType:e.type??`unknown`,iban:e.iban,bic:e.bic,currency:e.currency??`EUR`,accountNumberMasked:e.metadata?.account_number_masked,ownership:this.mapOwnership(e.metadata?.ownership),status:this.mapAccountStatus(e.status),lastSyncedAt:e.metadata?.last_sync_at,metadata:e.metadata}}mapAccountDetails(e,t){return{...this.mapAccount(e,t),productCode:e.metadata?.product_code,openedAt:e.metadata?.opened_at,closedAt:e.metadata?.closed_at,availableBalance:e.availableBalance??void 0,currentBalance:e.balance??void 0,creditLimit:e.metadata?.credit_limit,customFields:e.metadata}}mapTransaction(e,t){return{id:e.uuid,externalId:e.uuid,tenantId:t.tenantId,accountId:e.accountUuid,connectionId:t.connectionId,amount:e.amount,currency:e.currency,direction:e.direction===`credit`?`credit`:`debit`,description:e.description??e.rawLabel,bookingDate:e.bookingDate,valueDate:e.valueDate,postedAt:e.bookingDate,category:e.category,rawCategory:e.rawLabel,merchantName:e.merchantName,merchantCategoryCode:e.merchantCategoryCode,counterpartyName:e.counterpartyName,counterpartyAccount:e.counterpartyAccount,reference:e.metadata?.reference,status:this.mapTransactionStatus(e.status),metadata:e.metadata}}mapBalance(e,t){return{accountId:e.accountUuid,connectionId:t.connectionId,tenantId:t.tenantId,type:e.type??`current`,currency:e.currency??`EUR`,amount:e.amount,lastUpdatedAt:e.updatedAt,metadata:e.metadata}}toContext(e,t){return{tenantId:e,connectionId:t}}mapOwnership(e){switch(e?.toLowerCase()){case`individual`:case`personal`:return`individual`;case`joint`:return`joint`;case`business`:case`corporate`:return`business`;default:return`unknown`}}mapAccountStatus(e){switch(e?.toLowerCase()){case`active`:case`enabled`:return`active`;case`disabled`:case`inactive`:return`inactive`;case`closed`:return`closed`;case`suspended`:return`suspended`;default:return`active`}}mapTransactionStatus(e){switch(e?.toLowerCase()){case`pending`:case`authorised`:return`pending`;case`booked`:case`posted`:return`booked`;case`cancelled`:case`rejected`:return`cancelled`;default:return`booked`}}mapConnectionStatus(e){switch(e){case`healthy`:return`healthy`;case`pending`:return`degraded`;case`error`:return`error`;case`revoked`:return`disconnected`;default:return`degraded`}}handleError(t,n){throw n instanceof e?(this.logger?.error?.(`[PowensOpenBankingProvider] ${t} failed`,{status:n.status,code:n.code,requestId:n.requestId,message:n.message}),n):(this.logger?.error?.(`[PowensOpenBankingProvider] ${t} failed with unexpected error`,n),n instanceof Error?n:Error(`Powens operation "${t}" failed`))}};export{n};
+import { PowensClient, PowensClientError } from "./powens-client.js";
+
+//#region ../../integrations/providers-impls/dist/impls/powens-openbanking.js
+var PowensOpenBankingProvider = class {
+	client;
+	logger;
+	constructor(options) {
+		this.client = new PowensClient(options);
+		this.logger = options.logger;
+	}
+	async listAccounts(params) {
+		if (!params.userId) throw new PowensClientError("Powens account listing requires the upstream userId mapped to Powens user UUID.", 400);
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const response = await this.client.listAccounts({
+				userUuid: params.userId,
+				cursor: params.cursor,
+				limit: params.pageSize,
+				includeBalances: params.includeBalances,
+				institutionUuid: params.institutionId
+			});
+			return {
+				accounts: response.accounts.map((account) => this.mapAccount(account, context)),
+				nextCursor: response.pagination?.nextCursor,
+				hasMore: response.pagination?.hasMore
+			};
+		} catch (error) {
+			this.handleError("listAccounts", error);
+		}
+	}
+	async getAccountDetails(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const account = await this.client.getAccount(params.accountId);
+			return this.mapAccountDetails(account, context);
+		} catch (error) {
+			this.handleError("getAccountDetails", error);
+		}
+	}
+	async listTransactions(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const response = await this.client.listTransactions({
+				accountUuid: params.accountId,
+				cursor: params.cursor,
+				limit: params.pageSize,
+				from: params.from,
+				to: params.to,
+				includePending: params.includePending
+			});
+			return {
+				transactions: response.transactions.map((transaction) => this.mapTransaction(transaction, context)),
+				nextCursor: response.pagination?.nextCursor,
+				hasMore: response.pagination?.hasMore
+			};
+		} catch (error) {
+			this.handleError("listTransactions", error);
+		}
+	}
+	async getBalances(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			return (await this.client.getBalances(params.accountId)).filter((balance) => params.balanceTypes?.length ? params.balanceTypes.includes(balance.type) : true).map((balance) => this.mapBalance(balance, context));
+		} catch (error) {
+			this.handleError("getBalances", error);
+		}
+	}
+	async getConnectionStatus(params) {
+		try {
+			const status = await this.client.getConnectionStatus(params.connectionId);
+			return {
+				connectionId: params.connectionId,
+				tenantId: params.tenantId,
+				status: this.mapConnectionStatus(status.status),
+				lastCheckedAt: status.lastAttemptAt,
+				errorCode: status.errorCode,
+				errorMessage: status.errorMessage,
+				details: status.metadata
+			};
+		} catch (error) {
+			this.handleError("getConnectionStatus", error);
+		}
+	}
+	mapAccount(account, context) {
+		return {
+			id: account.uuid,
+			externalId: account.reference ?? account.uuid,
+			tenantId: context.tenantId,
+			connectionId: context.connectionId,
+			userId: account.userUuid,
+			displayName: account.name,
+			institutionId: account.institution.id,
+			institutionName: account.institution.name,
+			institutionLogoUrl: account.institution.logoUrl,
+			accountType: account.type ?? "unknown",
+			iban: account.iban,
+			bic: account.bic,
+			currency: account.currency ?? "EUR",
+			accountNumberMasked: account.metadata?.account_number_masked,
+			ownership: this.mapOwnership(account.metadata?.ownership),
+			status: this.mapAccountStatus(account.status),
+			lastSyncedAt: account.metadata?.last_sync_at,
+			metadata: account.metadata
+		};
+	}
+	mapAccountDetails(account, context) {
+		return {
+			...this.mapAccount(account, context),
+			productCode: account.metadata?.product_code,
+			openedAt: account.metadata?.opened_at,
+			closedAt: account.metadata?.closed_at,
+			availableBalance: account.availableBalance ?? void 0,
+			currentBalance: account.balance ?? void 0,
+			creditLimit: account.metadata?.credit_limit,
+			customFields: account.metadata
+		};
+	}
+	mapTransaction(transaction, context) {
+		return {
+			id: transaction.uuid,
+			externalId: transaction.uuid,
+			tenantId: context.tenantId,
+			accountId: transaction.accountUuid,
+			connectionId: context.connectionId,
+			amount: transaction.amount,
+			currency: transaction.currency,
+			direction: transaction.direction === "credit" ? "credit" : "debit",
+			description: transaction.description ?? transaction.rawLabel,
+			bookingDate: transaction.bookingDate,
+			valueDate: transaction.valueDate,
+			postedAt: transaction.bookingDate,
+			category: transaction.category,
+			rawCategory: transaction.rawLabel,
+			merchantName: transaction.merchantName,
+			merchantCategoryCode: transaction.merchantCategoryCode,
+			counterpartyName: transaction.counterpartyName,
+			counterpartyAccount: transaction.counterpartyAccount,
+			reference: transaction.metadata?.reference,
+			status: this.mapTransactionStatus(transaction.status),
+			metadata: transaction.metadata
+		};
+	}
+	mapBalance(balance, context) {
+		return {
+			accountId: balance.accountUuid,
+			connectionId: context.connectionId,
+			tenantId: context.tenantId,
+			type: balance.type ?? "current",
+			currency: balance.currency ?? "EUR",
+			amount: balance.amount,
+			lastUpdatedAt: balance.updatedAt,
+			metadata: balance.metadata
+		};
+	}
+	toContext(tenantId, connectionId) {
+		return {
+			tenantId,
+			connectionId
+		};
+	}
+	mapOwnership(value) {
+		switch (value?.toLowerCase()) {
+			case "individual":
+			case "personal": return "individual";
+			case "joint": return "joint";
+			case "business":
+			case "corporate": return "business";
+			default: return "unknown";
+		}
+	}
+	mapAccountStatus(status) {
+		switch (status?.toLowerCase()) {
+			case "active":
+			case "enabled": return "active";
+			case "disabled":
+			case "inactive": return "inactive";
+			case "closed": return "closed";
+			case "suspended": return "suspended";
+			default: return "active";
+		}
+	}
+	mapTransactionStatus(status) {
+		switch (status?.toLowerCase()) {
+			case "pending":
+			case "authorised": return "pending";
+			case "booked":
+			case "posted": return "booked";
+			case "cancelled":
+			case "rejected": return "cancelled";
+			default: return "booked";
+		}
+	}
+	mapConnectionStatus(status) {
+		switch (status) {
+			case "healthy": return "healthy";
+			case "pending": return "degraded";
+			case "error": return "error";
+			case "revoked": return "disconnected";
+			default: return "degraded";
+		}
+	}
+	handleError(operation, error) {
+		if (error instanceof PowensClientError) {
+			this.logger?.error?.(`[PowensOpenBankingProvider] ${operation} failed`, {
+				status: error.status,
+				code: error.code,
+				requestId: error.requestId,
+				message: error.message
+			});
+			throw error;
+		}
+		this.logger?.error?.(`[PowensOpenBankingProvider] ${operation} failed with unexpected error`, error);
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error(`Powens operation "${operation}" failed`);
+	}
+};
+
+//#endregion
+export { PowensOpenBankingProvider };

package/dist/libs/contracts/dist/docs/PUBLISHING.docblock.js

@@ -1,76 +1,16 @@
-import{a as e}from"./registry.js";e([{id:`docs.PUBLISHING`,title:`Publishing ContractSpec Libraries`,summary:`This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).`,kind:`reference`,visibility:`public`,route:`/docs/PUBLISHING`,tags:[`PUBLISHING`],body:`# Publishing ContractSpec Libraries
-
-This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).
-
-## Release Tracks
-
-| Track | Branch | npm Tag | Frequency | Versioning | Use Case |
-|-------|--------|---------|-----------|------------|----------|
-| **Stable** | \`release\` | \`latest\` | Manual | SemVer (e.g., \`1.7.4\`) | Production, external users |
-| **Canary** | \`main\` | \`canary\` | Every Push | Snapshot (e.g., \`1.7.4-canary...\`) | Dev, internal testing |
-
-## Prerequisites
-
-- ✅ \`NPM_TOKEN\` secret is configured in GitHub (owner or automation token with _publish_ scope).
-- ✅ \`GITHUB_TOKEN\` (built-in) has permissions to create PRs (enabled by default in new repos).
-- ✅ For stable releases: \`release\` branch exists and is protected.
-
-## Canary Workflow (Automatic)
-
-Every commit pushed to \`main\` triggers the \`.github/workflows/publish-canary.yml\` workflow.
-
-1. **Trigger**: Push to \`main\`.
-2. **Versioning**: Runs \`changeset version --snapshot canary\` to generate a temporary snapshot version.
-3. **Publish**: Packages are published to npm with the \`canary\` tag using \`changeset publish --tag canary\`.
-
-### Consuming Canary Builds
-
-To install the latest bleeding-edge version:
-
-\`\`\`bash
-npm install @lssm/lib.contracts@canary
-# or
-bun add @lssm/lib.contracts@canary
-\`\`\`
-
-## Stable Release Workflow (Manual)
-
-Stable releases are managed via the \`release\` branch using the standard [Changesets Action](https://github.com/changesets/action).
-
-1. **Develop on \`main\`**: Create features and fixes.
-2. **Add Changesets**: Run \`bun changeset\` to document changes and impact (major/minor/patch).
-3. **Merge to \`release\`**: When ready to ship, open a PR from \`main\` to \`release\` or merge manually.
-4. **"Version Packages" PR**:
-   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **"Version Packages"**.
-   - This PR contains the version bumps and updated \`CHANGELOG.md\` files.
-5. **Merge & Publish**:
-   - Review and merge the "Version Packages" PR.
-   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the \`latest\` tag.
-
-### Publishing Steps
-
-1. Ensure all changesets are present on \`main\`.
-2. Merge \`main\` into \`release\`:
-   \`\`\`bash
-   git checkout release
-   git pull origin release
-   git merge main
-   git push origin release
-   \`\`\`
-3. Go to GitHub Pull Requests. You will see a **"Version Packages"** PR created by the bot.
-4. Merge that PR.
-5. The release is now live on npm!
-
-## Manual Verification (Optional)
-
-Before publishing a new version you can run:
-
-\`\`\`bash
-bun run build:not-apps
-npx npm-packlist --json packages/libs/contracts
-\`\`\`
-
-## Rollback
-
-If a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use \`npm deprecate <package>@<version>\` if we need to warn consumers about a broken release.
-`}]);
+import { registerDocBlocks } from "./registry.js";
+
+//#region ../../libs/contracts/dist/docs/PUBLISHING.docblock.js
+const PUBLISHING_DocBlocks = [{
+	id: "docs.PUBLISHING",
+	title: "Publishing ContractSpec Libraries",
+	summary: "This guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/PUBLISHING",
+	tags: ["PUBLISHING"],
+	body: "# Publishing ContractSpec Libraries\n\nThis guide describes how we release the ContractSpec libraries to npm. We use a dual-track release system: **Stable** (manual) and **Canary** (automatic).\n\n## Release Tracks\n\n| Track | Branch | npm Tag | Frequency | Versioning | Use Case |\n|-------|--------|---------|-----------|------------|----------|\n| **Stable** | `release` | `latest` | Manual | SemVer (e.g., `1.7.4`) | Production, external users |\n| **Canary** | `main` | `canary` | Every Push | Snapshot (e.g., `1.7.4-canary...`) | Dev, internal testing |\n\n## Prerequisites\n\n- ✅ `NPM_TOKEN` secret is configured in GitHub (owner or automation token with _publish_ scope).\n- ✅ `GITHUB_TOKEN` (built-in) has permissions to create PRs (enabled by default in new repos).\n- ✅ For stable releases: `release` branch exists and is protected.\n\n## Canary Workflow (Automatic)\n\nEvery commit pushed to `main` triggers the `.github/workflows/publish-canary.yml` workflow.\n\n1. **Trigger**: Push to `main`.\n2. **Versioning**: Runs `changeset version --snapshot canary` to generate a temporary snapshot version.\n3. **Publish**: Packages are published to npm with the `canary` tag using `changeset publish --tag canary`.\n\n### Consuming Canary Builds\n\nTo install the latest bleeding-edge version:\n\n```bash\nnpm install @lssm/lib.contracts@canary\n# or\nbun add @lssm/lib.contracts@canary\n```\n\n## Stable Release Workflow (Manual)\n\nStable releases are managed via the `release` branch using the standard [Changesets Action](https://github.com/changesets/action).\n\n1. **Develop on `main`**: Create features and fixes.\n2. **Add Changesets**: Run `bun changeset` to document changes and impact (major/minor/patch).\n3. **Merge to `release`**: When ready to ship, open a PR from `main` to `release` or merge manually.\n4. **\"Version Packages\" PR**:\n   - The GitHub Action detects new changesets and automatically creates a Pull Request titled **\"Version Packages\"**.\n   - This PR contains the version bumps and updated `CHANGELOG.md` files.\n5. **Merge & Publish**:\n   - Review and merge the \"Version Packages\" PR.\n   - The Action runs again, detects the versions have been bumped, builds the libraries, and publishes them to npm with the `latest` tag.\n\n### Publishing Steps\n\n1. Ensure all changesets are present on `main`.\n2. Merge `main` into `release`:\n   ```bash\n   git checkout release\n   git pull origin release\n   git merge main\n   git push origin release\n   ```\n3. Go to GitHub Pull Requests. You will see a **\"Version Packages\"** PR created by the bot.\n4. Merge that PR.\n5. The release is now live on npm!\n\n## Manual Verification (Optional)\n\nBefore publishing a new version you can run:\n\n```bash\nbun run build:not-apps\nnpx npm-packlist --json packages/libs/contracts\n```\n\n## Rollback\n\nIf a publish fails mid-way, re-run the workflow once the issue is fixed. Already published packages are skipped automatically. Use `npm deprecate <package>@<version>` if we need to warn consumers about a broken release.\n"
+}];
+registerDocBlocks(PUBLISHING_DocBlocks);
+
+//#endregion