nirium 0.17.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -218,6 +218,28 @@ Runs on **your own server**, not Nirium's - `x402Serve()` is a client-side funct
218
218
 
219
219
  **Known limitation:** by default `x402Serve()` does not protect against replay and does not rate-limit callers. It is turned on by passing `guard` (see below).
220
220
 
221
+ #### Getting listed in an x402 Bazaar (optional)
222
+
223
+ Add `input`, `inputSchema`, and/or `output` to a route to declare its discovery metadata ([`@x402/extensions/bazaar`](https://www.npmjs.com/package/@x402/extensions)'s `declareDiscoveryExtension()`). A facilitator that reads the Bazaar extension (for example [Rail402](https://docs.rail402.dev/bazaar/discovery) on Stellar testnet) catalogs the route the first time a payment for it settles, so agents can discover it by searching instead of needing the URL hardcoded:
224
+
225
+ ```typescript
226
+ app.use('/premium', x402Serve({
227
+ payTo: 'G...',
228
+ routes: {
229
+ 'GET /signals': {
230
+ price: '$0.02',
231
+ description: 'Nirium arbitrage signals',
232
+ input: { count: 20 },
233
+ inputSchema: { properties: { count: { type: 'integer', maximum: 100 } } },
234
+ output: { example: { signals: [{ pair: 'XLM/USDC', confidence: 0.85 }] } },
235
+ },
236
+ },
237
+ facilitatorApiKey: '...',
238
+ }));
239
+ ```
240
+
241
+ Without `input`/`inputSchema`/`output`, a route behaves exactly as before - no `extensions` key, no new required dependency (`@x402/extensions` is only ever loaded if at least one route uses them).
242
+
221
243
  #### Replay and rate-limit guard (optional)
222
244
 
223
245
  Without `guard`, `x402Serve()` verifies and settles the payment and does nothing else. It does not stop the same signed payment from being sent twice, and it does not limit how often one caller can hit a route. Pass `guard` to get both:
package/dist/index.d.ts CHANGED
@@ -292,6 +292,21 @@ export interface PayoutRun {
292
292
  pricing?: Record<string, unknown>;
293
293
  [key: string]: unknown;
294
294
  }
295
+ /**
296
+ * One entry of the public payout history (getPayoutRuns). It carries what is
297
+ * already public on-chain - amount, asset, recipient count and the tx - and
298
+ * never the run id or the IPFS receipt CID: the receipt is the paying
299
+ * company's evidence, returned only to whoever runs the payout (submitPayout).
300
+ */
301
+ export interface PublicPayoutRun {
302
+ network?: string;
303
+ asset?: string;
304
+ totalAmount?: string;
305
+ recipientCount?: number;
306
+ txHash?: string;
307
+ explorer?: string;
308
+ signed?: boolean;
309
+ }
295
310
  export interface AgentAttestationInput {
296
311
  /** ed25519 public key of the agent, as a Stellar address (G...). */
297
312
  key: string;
@@ -717,9 +732,13 @@ export declare class Agent {
717
732
  }>;
718
733
  /** Broadcast the signed trustline XDR from onboardPayoutRecipient. */
719
734
  submitPayoutOnboard(signedXdr: string): Promise<Record<string, unknown>>;
720
- /** Payout history for the current network, each with tx hash and IPFS receipt CID. */
735
+ /**
736
+ * Public payout history for the current network: amount, asset, recipient
737
+ * count and tx hash. It does not include run ids or IPFS receipt CIDs; your
738
+ * own run's CID comes back from submitPayout().
739
+ */
721
740
  getPayoutRuns(): Promise<{
722
- runs: PayoutRun[];
741
+ runs: PublicPayoutRun[];
723
742
  }>;
724
743
  /** Payouts Terms v1.0 — the text `acknowledgeTerms` accepts. */
725
744
  getPayoutTerms(): Promise<Record<string, unknown>>;
@@ -900,10 +919,22 @@ export declare class Agent {
900
919
  export interface X402ServeConfig {
901
920
  /** Cuenta Stellar que recibe los pagos. Sin esto no hay a quién cobrarle. */
902
921
  payTo: string;
903
- /** `'GET /signals': '$0.02'` — el método es opcional y default GET. */
922
+ /**
923
+ * `'GET /signals': '$0.02'` — el método es opcional y default GET.
924
+ *
925
+ * `input`/`inputSchema`/`output` son opcionales y activan el discovery
926
+ * de x402 Bazaar (misma forma que `PREMIUM_ROUTES` en
927
+ * packages/agent/src/middleware/x402.ts): si cualquiera está presente,
928
+ * la ruta se anuncia vía `declareDiscoveryExtension()` y aparece en
929
+ * `GET /discovery/resources` del facilitador. Sin ellos, cero cambio de
930
+ * comportamiento respecto a antes de que este campo existiera.
931
+ */
904
932
  routes: Record<string, string | {
905
933
  price: string;
906
934
  description?: string;
935
+ input?: unknown;
936
+ inputSchema?: unknown;
937
+ output?: unknown;
907
938
  }>;
908
939
  network?: 'stellar:testnet' | 'stellar:pubnet';
909
940
  /** Default: OpenZeppelin Channels, el facilitador canónico de Stellar. */
package/dist/index.js CHANGED
@@ -342,7 +342,11 @@ class Agent {
342
342
  async submitPayoutOnboard(signedXdr) {
343
343
  return this.request('POST', '/api/payroll/onboard/submit', { signedXdr });
344
344
  }
345
- /** Payout history for the current network, each with tx hash and IPFS receipt CID. */
345
+ /**
346
+ * Public payout history for the current network: amount, asset, recipient
347
+ * count and tx hash. It does not include run ids or IPFS receipt CIDs; your
348
+ * own run's CID comes back from submitPayout().
349
+ */
346
350
  async getPayoutRuns() {
347
351
  return this.request('GET', '/api/payroll/runs');
348
352
  }
@@ -782,7 +786,7 @@ function x402Serve(config) {
782
786
  catch (err) {
783
787
  const missing = /cannot find (module|package)/i.test(String(err?.message));
784
788
  throw new Error(missing
785
- ? `x402Serve needs "${m}". Install it alongside the SDK: npm i @x402/express @x402/core @x402/stellar`
789
+ ? `x402Serve needs "${m}". Install it alongside the SDK: npm i @x402/express @x402/core @x402/stellar @x402/extensions`
786
790
  : `x402Serve could not load "${m}": ${err?.message}`);
787
791
  }
788
792
  };
@@ -794,7 +798,14 @@ function x402Serve(config) {
794
798
  });
795
799
  // 'GET /signals' y '/signals' significan lo mismo: el método se omite
796
800
  // porque casi todo cobro es un GET, y obligar a escribirlo es fricción.
801
+ //
802
+ // `discoverySpecs` guarda input/inputSchema/output por separado de
803
+ // `routes` porque convertirlos en `extensions.bazaar` requiere
804
+ // `declareDiscoveryExtension()` de `@x402/extensions/bazaar`, un import
805
+ // dinámico — y todo el resto de esta función carga sus dependencias
806
+ // dentro de build(), nunca aquí arriba de forma síncrona.
797
807
  const routes = {};
808
+ const discoverySpecs = {};
798
809
  for (const [key, value] of entries) {
799
810
  const spec = typeof value === 'string' ? { price: value } : value;
800
811
  const routeKey = /^[A-Z]+\s/.test(key) ? key : `GET ${key}`;
@@ -811,6 +822,13 @@ function x402Serve(config) {
811
822
  payTo: config.payTo,
812
823
  },
813
824
  };
825
+ if ('input' in spec || 'inputSchema' in spec || 'output' in spec) {
826
+ discoverySpecs[routeKey] = {
827
+ input: spec.input,
828
+ inputSchema: spec.inputSchema,
829
+ output: spec.output,
830
+ };
831
+ }
814
832
  }
815
833
  const facilitatorKeyHash = config.facilitatorApiKey
816
834
  ? (0, node_crypto_1.createHash)('sha256').update(config.facilitatorApiKey).digest('hex').slice(0, 16)
@@ -854,11 +872,22 @@ function x402Serve(config) {
854
872
  };
855
873
  let cached;
856
874
  const build = async () => {
857
- const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactStellarScheme: ServerScheme }] = await Promise.all([
875
+ const hasDiscovery = Object.keys(discoverySpecs).length > 0;
876
+ const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactStellarScheme: ServerScheme }, bazaar] = await Promise.all([
858
877
  load('@x402/express'),
859
878
  load('@x402/core/server'),
860
879
  load('@x402/stellar/exact/server'),
880
+ hasDiscovery ? load('@x402/extensions/bazaar') : Promise.resolve(undefined),
861
881
  ]);
882
+ if (bazaar) {
883
+ const { declareDiscoveryExtension } = bazaar;
884
+ for (const [routeKey, discovery] of Object.entries(discoverySpecs)) {
885
+ // Solo los campos que de verdad se pasaron — `output: undefined`
886
+ // no debería terminar escrito literal en el discovery.
887
+ const fields = Object.fromEntries(Object.entries(discovery).filter(([, v]) => v !== undefined));
888
+ routes[routeKey].extensions = declareDiscoveryExtension(fields);
889
+ }
890
+ }
862
891
  const facilitator = new HTTPFacilitatorClient({
863
892
  url: facilitatorUrl,
864
893
  ...(config.facilitatorApiKey ? {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium",
3
- "version": "0.17.0",
3
+ "version": "0.19.0",
4
4
  "description": "Autonomous treasury and agentic-payments infrastructure for Stellar (x402)",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -62,6 +62,8 @@
62
62
  "@types/node": "^26.2.0",
63
63
  "@types/ws": "^8.18.1",
64
64
  "@x402/core": "^2.28.0",
65
+ "@x402/express": "^2.28.0",
66
+ "@x402/extensions": "^2.28.0",
65
67
  "jest": "^30.4.2",
66
68
  "ts-jest": "^29.4.12",
67
69
  "typescript": "^5.9.3"