nirium 0.17.0 → 0.18.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
@@ -900,10 +900,22 @@ export declare class Agent {
900
900
  export interface X402ServeConfig {
901
901
  /** Cuenta Stellar que recibe los pagos. Sin esto no hay a quién cobrarle. */
902
902
  payTo: string;
903
- /** `'GET /signals': '$0.02'` — el método es opcional y default GET. */
903
+ /**
904
+ * `'GET /signals': '$0.02'` — el método es opcional y default GET.
905
+ *
906
+ * `input`/`inputSchema`/`output` son opcionales y activan el discovery
907
+ * de x402 Bazaar (misma forma que `PREMIUM_ROUTES` en
908
+ * packages/agent/src/middleware/x402.ts): si cualquiera está presente,
909
+ * la ruta se anuncia vía `declareDiscoveryExtension()` y aparece en
910
+ * `GET /discovery/resources` del facilitador. Sin ellos, cero cambio de
911
+ * comportamiento respecto a antes de que este campo existiera.
912
+ */
904
913
  routes: Record<string, string | {
905
914
  price: string;
906
915
  description?: string;
916
+ input?: unknown;
917
+ inputSchema?: unknown;
918
+ output?: unknown;
907
919
  }>;
908
920
  network?: 'stellar:testnet' | 'stellar:pubnet';
909
921
  /** Default: OpenZeppelin Channels, el facilitador canónico de Stellar. */
package/dist/index.js CHANGED
@@ -782,7 +782,7 @@ function x402Serve(config) {
782
782
  catch (err) {
783
783
  const missing = /cannot find (module|package)/i.test(String(err?.message));
784
784
  throw new Error(missing
785
- ? `x402Serve needs "${m}". Install it alongside the SDK: npm i @x402/express @x402/core @x402/stellar`
785
+ ? `x402Serve needs "${m}". Install it alongside the SDK: npm i @x402/express @x402/core @x402/stellar @x402/extensions`
786
786
  : `x402Serve could not load "${m}": ${err?.message}`);
787
787
  }
788
788
  };
@@ -794,7 +794,14 @@ function x402Serve(config) {
794
794
  });
795
795
  // 'GET /signals' y '/signals' significan lo mismo: el método se omite
796
796
  // porque casi todo cobro es un GET, y obligar a escribirlo es fricción.
797
+ //
798
+ // `discoverySpecs` guarda input/inputSchema/output por separado de
799
+ // `routes` porque convertirlos en `extensions.bazaar` requiere
800
+ // `declareDiscoveryExtension()` de `@x402/extensions/bazaar`, un import
801
+ // dinámico — y todo el resto de esta función carga sus dependencias
802
+ // dentro de build(), nunca aquí arriba de forma síncrona.
797
803
  const routes = {};
804
+ const discoverySpecs = {};
798
805
  for (const [key, value] of entries) {
799
806
  const spec = typeof value === 'string' ? { price: value } : value;
800
807
  const routeKey = /^[A-Z]+\s/.test(key) ? key : `GET ${key}`;
@@ -811,6 +818,13 @@ function x402Serve(config) {
811
818
  payTo: config.payTo,
812
819
  },
813
820
  };
821
+ if ('input' in spec || 'inputSchema' in spec || 'output' in spec) {
822
+ discoverySpecs[routeKey] = {
823
+ input: spec.input,
824
+ inputSchema: spec.inputSchema,
825
+ output: spec.output,
826
+ };
827
+ }
814
828
  }
815
829
  const facilitatorKeyHash = config.facilitatorApiKey
816
830
  ? (0, node_crypto_1.createHash)('sha256').update(config.facilitatorApiKey).digest('hex').slice(0, 16)
@@ -854,11 +868,22 @@ function x402Serve(config) {
854
868
  };
855
869
  let cached;
856
870
  const build = async () => {
857
- const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactStellarScheme: ServerScheme }] = await Promise.all([
871
+ const hasDiscovery = Object.keys(discoverySpecs).length > 0;
872
+ const [{ paymentMiddlewareFromConfig }, { HTTPFacilitatorClient }, { ExactStellarScheme: ServerScheme }, bazaar] = await Promise.all([
858
873
  load('@x402/express'),
859
874
  load('@x402/core/server'),
860
875
  load('@x402/stellar/exact/server'),
876
+ hasDiscovery ? load('@x402/extensions/bazaar') : Promise.resolve(undefined),
861
877
  ]);
878
+ if (bazaar) {
879
+ const { declareDiscoveryExtension } = bazaar;
880
+ for (const [routeKey, discovery] of Object.entries(discoverySpecs)) {
881
+ // Solo los campos que de verdad se pasaron — `output: undefined`
882
+ // no debería terminar escrito literal en el discovery.
883
+ const fields = Object.fromEntries(Object.entries(discovery).filter(([, v]) => v !== undefined));
884
+ routes[routeKey].extensions = declareDiscoveryExtension(fields);
885
+ }
886
+ }
862
887
  const facilitator = new HTTPFacilitatorClient({
863
888
  url: facilitatorUrl,
864
889
  ...(config.facilitatorApiKey ? {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium",
3
- "version": "0.17.0",
3
+ "version": "0.18.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"