@limetry/sdk 1.2.42

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.
@@ -0,0 +1,712 @@
1
+ /**
2
+ * Shared TypeScript contracts for Limetry policy evaluation and agent tooling.
3
+ *
4
+ * Covers spending and action policies, transaction/action intents, evaluation
5
+ * request/response shapes, and chat-completion client stubs used by adapters.
6
+ */
7
+ /**
8
+ * Lifecycle status of a published spending or action policy.
9
+ */
10
+ export type PolicyStatus = "active" | "suspended" | "revoked";
11
+ /**
12
+ * Lifecycle status of a spending {@link TransactionIntent}.
13
+ */
14
+ export type IntentStatus = "draft" | "pending_policy_evaluation" | "approved" | "rejected" | "expired" | "signed" | "executed";
15
+ /**
16
+ * Merchant / spend category discriminator for payment intents.
17
+ *
18
+ * `Other` carries a free-form `label`; other kinds are fixed tags.
19
+ */
20
+ export type TransactionCategory = {
21
+ kind: "SoftwareSubscription";
22
+ } | {
23
+ kind: "CloudInfrastructure";
24
+ } | {
25
+ kind: "ProfessionalServices";
26
+ } | {
27
+ kind: "Marketplace";
28
+ } | {
29
+ kind: "Other";
30
+ label: string;
31
+ };
32
+ /**
33
+ * Currency-denominated spending caps in minor units (for example cents).
34
+ */
35
+ export type SpendingLimits = {
36
+ /**
37
+ * Maximum amount allowed for a single transaction.
38
+ */
39
+ max_single_transaction_minor: number;
40
+ /**
41
+ * Maximum aggregate spend allowed within a rolling day.
42
+ */
43
+ max_daily_spend_minor: number;
44
+ /**
45
+ * Maximum aggregate spend allowed within a rolling month.
46
+ */
47
+ max_monthly_spend_minor: number;
48
+ /**
49
+ * ISO 4217 currency code applying to the minor-unit amounts.
50
+ */
51
+ currency: string;
52
+ };
53
+ /**
54
+ * Rate and volume caps that bound how fast an agent may spend.
55
+ */
56
+ export type VelocityLimits = {
57
+ /**
58
+ * Maximum number of transactions allowed per minute.
59
+ */
60
+ max_transactions_per_minute: number;
61
+ /**
62
+ * Maximum number of transactions allowed per hour.
63
+ */
64
+ max_transactions_per_hour: number;
65
+ /**
66
+ * Maximum number of transactions allowed per day.
67
+ */
68
+ max_transactions_per_day: number;
69
+ /**
70
+ * Maximum aggregate spend (minor units) allowed per hour.
71
+ */
72
+ max_aggregate_amount_per_hour_minor: number;
73
+ };
74
+ /**
75
+ * Nonce and clock rules that defend against replayed intents.
76
+ */
77
+ export type ReplayProtectionConfig = {
78
+ /**
79
+ * How long (seconds) a nonce remains valid after issue.
80
+ */
81
+ nonce_window_seconds: number;
82
+ /**
83
+ * Maximum allowed clock skew (seconds) when validating timestamps.
84
+ */
85
+ max_clock_skew_seconds: number;
86
+ /**
87
+ * When true, nonces must increase monotonically per agent.
88
+ */
89
+ require_monotonic_nonce: boolean;
90
+ };
91
+ /**
92
+ * Concurrency and TTL bounds for in-flight payment intents.
93
+ */
94
+ export type IsolationBounds = {
95
+ /**
96
+ * Maximum number of pending intents allowed at once.
97
+ */
98
+ max_concurrent_pending_intents: number;
99
+ /**
100
+ * Maximum aggregate pending amount (minor units).
101
+ */
102
+ max_pending_aggregate_minor: number;
103
+ /**
104
+ * Time-to-live (seconds) for a pending intent before expiry.
105
+ */
106
+ intent_ttl_seconds: number;
107
+ /**
108
+ * When true, a batch may not target the same payee more than once.
109
+ */
110
+ enforce_unique_payee_per_intent_batch: boolean;
111
+ };
112
+ /**
113
+ * Merchant and MCC allow/block rules for payment destinations.
114
+ */
115
+ export type DestinationRules = {
116
+ /**
117
+ * Merchant IDs that are explicitly allowed.
118
+ */
119
+ allowed_merchant_ids: string[];
120
+ /**
121
+ * Merchant Category Codes that are explicitly allowed.
122
+ */
123
+ allowed_mcc_codes: string[];
124
+ /**
125
+ * Merchant IDs that are explicitly blocked.
126
+ */
127
+ blocked_merchant_ids: string[];
128
+ /**
129
+ * When true, payees must appear on `allowed_merchant_ids`.
130
+ */
131
+ require_merchant_allowlist: boolean;
132
+ };
133
+ /**
134
+ * Inclusive start and optional end of a policy's effective period (ISO-8601).
135
+ */
136
+ export type EffectiveWindow = {
137
+ /**
138
+ * Instant from which the policy is effective.
139
+ */
140
+ effective_from: string;
141
+ /**
142
+ * Instant at which the policy stops being effective, or `null` if open-ended.
143
+ */
144
+ expires_at: string | null;
145
+ };
146
+ /**
147
+ * Full spending policy document evaluated for payment {@link TransactionIntent}s.
148
+ */
149
+ export type SpendingPolicy = {
150
+ /**
151
+ * Stable identifier for this policy document.
152
+ */
153
+ policy_id: string;
154
+ /**
155
+ * Monotonic policy revision number.
156
+ */
157
+ version: number;
158
+ /**
159
+ * Tenant / organization that owns the policy.
160
+ */
161
+ organization_id: string;
162
+ /**
163
+ * Agent identity the policy governs.
164
+ */
165
+ agent_id: string;
166
+ /**
167
+ * Per-transaction and aggregate spend caps.
168
+ */
169
+ limits: SpendingLimits;
170
+ /**
171
+ * Velocity / rate limits.
172
+ */
173
+ velocity: VelocityLimits;
174
+ /**
175
+ * Replay-protection settings.
176
+ */
177
+ replay: ReplayProtectionConfig;
178
+ /**
179
+ * Pending-intent isolation bounds.
180
+ */
181
+ isolation: IsolationBounds;
182
+ /**
183
+ * Destination allow/block rules.
184
+ */
185
+ destination_rules: DestinationRules;
186
+ /**
187
+ * Time window during which the policy is active.
188
+ */
189
+ effective_window: EffectiveWindow;
190
+ /**
191
+ * Current lifecycle status.
192
+ */
193
+ status: PolicyStatus;
194
+ /**
195
+ * Last update timestamp (ISO-8601).
196
+ */
197
+ updated_at: string;
198
+ };
199
+ /**
200
+ * Generic agent action intent evaluated by {@link PolicyEngine.evaluateAction}.
201
+ */
202
+ export type ActionIntent = {
203
+ /**
204
+ * Caller-supplied intent identifier (idempotency / correlation).
205
+ */
206
+ intent_id: string;
207
+ /**
208
+ * Policy document to evaluate against.
209
+ */
210
+ policy_id: string;
211
+ /**
212
+ * Agent that issued the intent.
213
+ */
214
+ agent_id: string;
215
+ /**
216
+ * Action verb / type string (for example `http.request` or `db.query`).
217
+ */
218
+ action_type: string;
219
+ /**
220
+ * Target resource identifier (URL, ARN, table, etc.).
221
+ */
222
+ resource: string;
223
+ /**
224
+ * Optional cost associated with the action, in minor units.
225
+ */
226
+ cost?: {
227
+ amount_minor: number;
228
+ currency: string;
229
+ };
230
+ /**
231
+ * Optional string key/value bag attached to the intent.
232
+ */
233
+ metadata?: Record<string, string>;
234
+ /**
235
+ * Issue timestamp (ISO-8601).
236
+ */
237
+ issued_at: string;
238
+ /**
239
+ * Optional replay nonce (string or number depending on caller).
240
+ */
241
+ nonce?: string | number;
242
+ };
243
+ /**
244
+ * Generic action policy constraining which actions an agent may perform.
245
+ */
246
+ export type ActionPolicy = {
247
+ /**
248
+ * Stable identifier for this policy document.
249
+ */
250
+ policy_id: string;
251
+ /**
252
+ * Monotonic policy revision number.
253
+ */
254
+ version: number;
255
+ /**
256
+ * Tenant / organization that owns the policy.
257
+ */
258
+ organization_id: string;
259
+ /**
260
+ * Agent identity the policy governs.
261
+ */
262
+ agent_id: string;
263
+ /**
264
+ * Action types that are permitted when other rules pass.
265
+ */
266
+ allowed_action_types: string[];
267
+ /**
268
+ * Action types that are always denied.
269
+ */
270
+ denied_action_types?: string[];
271
+ /**
272
+ * Glob/pattern list of resources that are allowed.
273
+ */
274
+ allowed_resource_patterns?: string[];
275
+ /**
276
+ * Glob/pattern list of resources that are blocked.
277
+ */
278
+ blocked_resource_patterns?: string[];
279
+ /**
280
+ * Maximum allowed `intent.cost.amount_minor` when cost is present.
281
+ */
282
+ max_cost_minor?: number;
283
+ /**
284
+ * Currency expected for cost checks when set.
285
+ */
286
+ currency?: string;
287
+ /**
288
+ * Action types that pass allow rules but still require human approval.
289
+ */
290
+ require_approval_action_types?: string[];
291
+ /**
292
+ * Resource patterns that force approval when matched.
293
+ */
294
+ require_approval_resource_patterns?: string[];
295
+ /**
296
+ * Cost threshold (inclusive) that forces approval when intent.cost is set.
297
+ */
298
+ approval_cost_minor?: number;
299
+ /**
300
+ * How much intent content to retain in audit storage after secret scrubbing.
301
+ * Defaults to minimal when omitted.
302
+ */
303
+ audit_mode?: "minimal" | "forensics";
304
+ /**
305
+ * Current lifecycle status.
306
+ */
307
+ status: PolicyStatus;
308
+ /**
309
+ * Last update timestamp (ISO-8601).
310
+ */
311
+ updated_at: string;
312
+ /**
313
+ * Optional start of the effective window (ISO-8601).
314
+ */
315
+ effective_from?: string;
316
+ /**
317
+ * Optional end of the effective window, or `null` if open-ended.
318
+ */
319
+ expires_at?: string | null;
320
+ };
321
+ /**
322
+ * Decision returned for an evaluated {@link ActionIntent}.
323
+ */
324
+ export type ActionDecision = "allow" | "deny" | "approval_required";
325
+ /**
326
+ * Payee identity attached to a payment {@link TransactionIntent}.
327
+ */
328
+ export type PayeeDescriptor = {
329
+ /**
330
+ * Merchant identifier used for allow/block matching.
331
+ */
332
+ merchant_id: string;
333
+ /**
334
+ * Human-readable merchant name.
335
+ */
336
+ merchant_name: string;
337
+ /**
338
+ * Merchant Category Code, or `null` when unknown.
339
+ */
340
+ mcc_code: string | null;
341
+ /**
342
+ * Optional rail / routing hint for the payment processor.
343
+ */
344
+ routing_hint: string | null;
345
+ };
346
+ /**
347
+ * Monetary amount in minor units plus currency code.
348
+ */
349
+ export type MoneyAmount = {
350
+ /**
351
+ * Amount in minor units (for example cents).
352
+ */
353
+ amount_minor: number;
354
+ /**
355
+ * ISO 4217 currency code.
356
+ */
357
+ currency: string;
358
+ };
359
+ /**
360
+ * Payment intent subject to spending-policy evaluation.
361
+ */
362
+ export type TransactionIntent = {
363
+ /**
364
+ * Unique intent identifier.
365
+ */
366
+ intent_id: string;
367
+ /**
368
+ * Policy document governing this intent.
369
+ */
370
+ policy_id: string;
371
+ /**
372
+ * Agent that issued the intent.
373
+ */
374
+ agent_id: string;
375
+ /**
376
+ * Amount to transfer.
377
+ */
378
+ amount: MoneyAmount;
379
+ /**
380
+ * Destination merchant descriptor.
381
+ */
382
+ payee: PayeeDescriptor;
383
+ /**
384
+ * Spend category for reporting and policy rules.
385
+ */
386
+ category: TransactionCategory;
387
+ /**
388
+ * Short human-readable memo.
389
+ */
390
+ memo: string;
391
+ /**
392
+ * Issue timestamp (ISO-8601).
393
+ */
394
+ issued_at: string;
395
+ /**
396
+ * Expiry timestamp (ISO-8601).
397
+ */
398
+ expires_at: string;
399
+ /**
400
+ * Monotonic replay nonce.
401
+ */
402
+ nonce: number;
403
+ /**
404
+ * Caller idempotency key for safe retries.
405
+ */
406
+ idempotency_key: string;
407
+ /**
408
+ * Opaque string metadata bag.
409
+ */
410
+ metadata: Record<string, string>;
411
+ /**
412
+ * Current intent lifecycle status.
413
+ */
414
+ status: IntentStatus;
415
+ };
416
+ /**
417
+ * Opaque engine state returned alongside spending evaluations.
418
+ *
419
+ * Shape is engine-defined; clients should treat fields as pass-through.
420
+ */
421
+ export type EvaluationState = {
422
+ /**
423
+ * Velocity ledger snapshot from the evaluating engine.
424
+ */
425
+ velocity_ledger: Record<string, unknown>;
426
+ /**
427
+ * Replay-store snapshot from the evaluating engine.
428
+ */
429
+ replay_store: Record<string, unknown>;
430
+ };
431
+ /**
432
+ * Successful spending-policy evaluation outcome summary.
433
+ */
434
+ export type EvaluationOutcome = {
435
+ /**
436
+ * Whether the intent was approved.
437
+ */
438
+ approved: boolean;
439
+ /**
440
+ * Evaluated intent identifier.
441
+ */
442
+ intent_id: string;
443
+ /**
444
+ * Evaluation timestamp (ISO-8601).
445
+ */
446
+ evaluated_at: string;
447
+ /**
448
+ * Remaining daily spend capacity in minor units after this decision.
449
+ */
450
+ remaining_daily_spend_minor: number;
451
+ /**
452
+ * Remaining single-transaction capacity in minor units after this decision.
453
+ */
454
+ remaining_single_transaction_minor: number;
455
+ };
456
+ /**
457
+ * Discriminated response for spending-policy evaluation.
458
+ *
459
+ * `ok: true` carries an {@link EvaluationOutcome}; `ok: false` carries a
460
+ * violation object and/or error string.
461
+ */
462
+ export type PolicyEvaluationResponse = {
463
+ /**
464
+ * Indicates a successful evaluation path.
465
+ */
466
+ ok: true;
467
+ /**
468
+ * Approved/denied outcome details.
469
+ */
470
+ outcome: EvaluationOutcome;
471
+ /**
472
+ * Updated engine state after evaluation.
473
+ */
474
+ state: EvaluationState;
475
+ } | {
476
+ /**
477
+ * Indicates a failed or rejected evaluation path.
478
+ */
479
+ ok: false;
480
+ /**
481
+ * Structured policy violation payload when available.
482
+ */
483
+ violation?: Record<string, unknown>;
484
+ /**
485
+ * Human-readable error when no structured violation is present.
486
+ */
487
+ error?: string;
488
+ /**
489
+ * Optional engine state after the failed evaluation.
490
+ */
491
+ state?: EvaluationState;
492
+ };
493
+ /**
494
+ * Outcome summary for an action-policy evaluation.
495
+ */
496
+ export type ActionEvaluationOutcome = {
497
+ /**
498
+ * Whether the action was approved (allow path).
499
+ */
500
+ approved: boolean;
501
+ /**
502
+ * Explicit decision enum when the server provides one.
503
+ */
504
+ decision?: ActionDecision;
505
+ /**
506
+ * Evaluated intent identifier.
507
+ */
508
+ intent_id: string;
509
+ /**
510
+ * Evaluation timestamp (ISO-8601).
511
+ */
512
+ evaluated_at: string;
513
+ /**
514
+ * Human-readable reasons for the decision.
515
+ */
516
+ reasons?: string[];
517
+ /**
518
+ * Stable decision identifier for audit correlation.
519
+ */
520
+ decision_id?: string;
521
+ /**
522
+ * Approval workflow identifier when `decision` is `approval_required`.
523
+ */
524
+ approval_id?: string;
525
+ };
526
+ /**
527
+ * Discriminated response for action-policy evaluation.
528
+ *
529
+ * Success payloads may include a nested `outcome`, top-level decision fields,
530
+ * and an optional receipt; failure payloads mirror spending evaluation errors.
531
+ */
532
+ export type ActionEvaluationResponse = {
533
+ /**
534
+ * Indicates a successful evaluation path.
535
+ */
536
+ ok: true;
537
+ /**
538
+ * Convenience approved flag mirrored from the outcome when present.
539
+ */
540
+ approved?: boolean;
541
+ /**
542
+ * Explicit decision enum when provided by the engine.
543
+ */
544
+ decision?: ActionDecision;
545
+ /**
546
+ * Human-readable reasons for the decision.
547
+ */
548
+ reasons?: string[];
549
+ /**
550
+ * Stable decision identifier for audit correlation.
551
+ */
552
+ decision_id?: string;
553
+ /**
554
+ * Approval workflow identifier when approval is required.
555
+ */
556
+ approval_id?: string;
557
+ /**
558
+ * Opaque decision receipt returned by the server.
559
+ */
560
+ receipt?: Record<string, unknown>;
561
+ /**
562
+ * Structured outcome summary when provided.
563
+ */
564
+ outcome?: ActionEvaluationOutcome;
565
+ /**
566
+ * Optional engine state after evaluation.
567
+ */
568
+ state?: EvaluationState;
569
+ } | {
570
+ /**
571
+ * Indicates a failed or rejected evaluation path.
572
+ */
573
+ ok: false;
574
+ /**
575
+ * Structured policy violation payload when available.
576
+ */
577
+ violation?: Record<string, unknown>;
578
+ /**
579
+ * Human-readable error when no structured violation is present.
580
+ */
581
+ error?: string;
582
+ /**
583
+ * Optional engine state after the failed evaluation.
584
+ */
585
+ state?: EvaluationState;
586
+ };
587
+ /**
588
+ * Arguments for a payment-execution tool call intercepted by Limetry adapters.
589
+ */
590
+ export type PaymentExecutionToolArgs = {
591
+ /**
592
+ * Destination merchant identifier.
593
+ */
594
+ merchant_id: string;
595
+ /**
596
+ * Destination merchant display name.
597
+ */
598
+ merchant_name: string;
599
+ /**
600
+ * Transfer amount in minor units.
601
+ */
602
+ amount_minor: number;
603
+ /**
604
+ * ISO 4217 currency code.
605
+ */
606
+ currency: string;
607
+ /**
608
+ * Short payment memo.
609
+ */
610
+ memo: string;
611
+ /**
612
+ * Spend category for the transfer.
613
+ */
614
+ category: TransactionCategory;
615
+ /**
616
+ * Idempotency key for the tool invocation.
617
+ */
618
+ idempotency_key: string;
619
+ };
620
+ /**
621
+ * OpenAI-style chat tool call attached to a completion message.
622
+ */
623
+ export type ChatToolCall = {
624
+ /**
625
+ * Tool call identifier.
626
+ */
627
+ id: string;
628
+ /**
629
+ * Discriminator; currently always `"function"`.
630
+ */
631
+ type: "function";
632
+ /**
633
+ * Function name and JSON-encoded argument string.
634
+ */
635
+ function: {
636
+ /**
637
+ * Registered tool / function name.
638
+ */
639
+ name: string;
640
+ /**
641
+ * JSON string of function arguments.
642
+ */
643
+ arguments: string;
644
+ };
645
+ };
646
+ /**
647
+ * Minimal chat-completion request shape accepted by {@link ChatCompletionClient}.
648
+ */
649
+ export type ChatCompletionRequest = {
650
+ /**
651
+ * Model identifier passed to the upstream provider.
652
+ */
653
+ model: string;
654
+ /**
655
+ * Conversation messages (provider-specific message objects).
656
+ */
657
+ messages: Array<Record<string, unknown>>;
658
+ /**
659
+ * Optional tool definitions offered to the model.
660
+ */
661
+ tools?: Array<Record<string, unknown>>;
662
+ };
663
+ /**
664
+ * Minimal chat-completion response shape returned by {@link ChatCompletionClient}.
665
+ */
666
+ export type ChatCompletionResponse = {
667
+ /**
668
+ * Completion choices; Limetry adapters read the first message's tool calls.
669
+ */
670
+ choices: Array<{
671
+ /**
672
+ * Assistant message for this choice.
673
+ */
674
+ message: {
675
+ /**
676
+ * Message role (typically `"assistant"`).
677
+ */
678
+ role: string;
679
+ /**
680
+ * Text content, or `null` when only tool calls are present.
681
+ */
682
+ content: string | null;
683
+ /**
684
+ * Optional tool calls requested by the model.
685
+ */
686
+ tool_calls?: ChatToolCall[];
687
+ };
688
+ }>;
689
+ };
690
+ /**
691
+ * Narrow OpenAI-compatible client surface used to intercept payment tool calls.
692
+ */
693
+ export type ChatCompletionClient = {
694
+ /**
695
+ * Chat API namespace.
696
+ */
697
+ chat: {
698
+ /**
699
+ * Completions API namespace.
700
+ */
701
+ completions: {
702
+ /**
703
+ * Creates a chat completion for the given request.
704
+ *
705
+ * @param request - Chat completion request payload.
706
+ * @returns Promise resolving to the provider response.
707
+ */
708
+ create: (request: ChatCompletionRequest) => Promise<ChatCompletionResponse>;
709
+ };
710
+ };
711
+ };
712
+ //# sourceMappingURL=types.d.ts.map