@vivoa/plugin-sdk 0.6.3 → 0.6.6

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/dist/index.d.ts CHANGED
@@ -1,367 +1,11 @@
1
+ import { F as FieldType, C as ConfigScope, S as SelectOption, P as PluginConfigField } from './host-api-C1VylW5l.js';
2
+ export { A as AUTHOR_HANDLE_RE, a as AccordionBlock, b as AccordionSection, c as ActionBlock, d as ActionVariant, e as AnalyticsActionSource, f as AnalyticsConsent, g as AnalyticsEvent, h as AnalyticsEventName, i as AnalyticsFeature, j as AnalyticsItem, k as AnalyticsMoney, l as AnalyticsPluginConfig, m as AnalyticsStaticConfig, n as AnalyticsUserData, o as AnalyticsUtm, p as AuthorValidation, B as BannerBlock, q as Block, r as BlockBase, s as BlockType, t as CalloutBlock, u as Capability, v as CapabilityKind, w as CardBlock, x as CodConfig, y as CodFeeConfig, z as CodFeeType, D as ConditionalBlock, E as ConditionalEquals, G as ConditionalWhen, H as ConfigurablePlugin, I as CopyFieldBlock, J as CreateShipmentParams, K as DispatchContext, L as DividerBlock, M as DomainEventHandler, N as DomainEventName, O as EmbedInit, Q as FieldBlock, R as FieldOption, T as FieldVariant, U as GatewayEnvironment, V as GatewayStaticConfig, W as GroupBlock, X as HostApi, Y as HttpClient, Z as HttpRequest, _ as HttpResponse, $ as IAnalyticsPlugin, a0 as IInvoicingPlugin, a1 as IPaymentPlugin, a2 as IPlugin, a3 as IShippingPlugin, a4 as ISuppliersPlugin, a5 as InlineRowBlock, a6 as InvoiceDocumentType, a7 as InvoiceLine, a8 as InvoiceMoney, a9 as InvoiceParty, aa as InvoiceRequest, ab as InvoiceResult, ac as InvoiceStatus, ad as InvoiceTax, ae as InvoicingDefaultConfig, af as InvoicingFeature, ag as InvoicingPluginConfig, ah as InvoicingStaticConfig, ai as KeyValueBlock, aj as KeyValueRow, ak as LayoutMode, al as Logger, am as MarkdownBlock, an as MessageVariant, ao as PaymentCard, ap as PaymentCustomer, aq as PaymentGatewayCode, ar as PaymentPayload, as as PaymentPluginConfig, at as PaymentRenderMode, au as PaymentResult, av as PaymentSessionPayload, aw as PaymentSessionResult, ax as PaymentVerifyPayload, ay as PlaceSupplierOrderInput, az as Plugin, aA as PluginActionContext, aB as PluginActionResult, aC as PluginAuthor, aD as PluginConfigFieldDependency, aE as PluginFactory, aF as PluginManifest, aG as PluginType, aH as RepeaterBlock, aI as RepeaterSource, aJ as SecretStore, aK as SequenceStore, aL as SetupAction, aM as SetupLayout, aN as SetupLayoutValidation, aO as SetupStep, aP as ShipmentAddress, aQ as ShipmentParcel, aR as ShipmentResult, aS as ShippingDefaultConfig, aT as ShippingFeature, aU as ShippingPluginConfig, aV as ShippingQuote, aW as ShippingQuoteParams, aX as ShippingStaticConfig, aY as StepStatusFrom, aZ as StepStatusFromAction, a_ as StepStatusFromFields, a$ as StepStatusSource, b0 as StorageBroker, b1 as SupplierCatalogQuery, b2 as SupplierFulfillmentEvent, b3 as SupplierListing, b4 as SupplierListingAttribute, b5 as SupplierListingPage, b6 as SupplierListingVariant, b7 as SupplierMoney, b8 as SupplierOrderAddressLevel, b9 as SupplierOrderCustomer, ba as SupplierOrderLine, bb as SupplierOrderResult, bc as SupplierOrderStatus, bd as SupplierShipTo, be as SupplierStock, bf as SuppliersDefaultConfig, bg as SuppliersFeature, bh as SuppliersPluginConfig, bi as SuppliersStaticConfig, bj as TabItem, bk as TabsBlock, bl as ToggleBlock, bm as TrackingEvent, bn as TransactionStatus, bo as VoidInvoiceInput, bp as WebhookSignatureResult, bq as analyticsCapability, br as capability, bs as crossValidateSetupLayout, bt as definePlugin, bu as invoicingCapability, bv as isConfigurablePlugin, bw as isPluginFactory, bx as paymentCapability, by as shippingCapability, bz as suppliersCapability, bA as validatePluginAuthor, bB as validateSetupLayout } from './host-api-C1VylW5l.js';
3
+
1
4
  declare const PAYMENT_PLUGIN_TOKEN: "PAYMENT_PLUGINS";
2
5
  declare const SHIPPING_PLUGIN_TOKEN: "SHIPPING_PLUGINS";
3
6
  declare const SUPPLIERS_PLUGIN_TOKEN: "SUPPLIERS_PLUGINS";
4
7
  declare const ANALYTICS_PLUGIN_TOKEN: "ANALYTICS_PLUGINS";
5
-
6
- declare enum FieldType {
7
- String = "string",
8
- Password = "password",
9
- Url = "url",
10
- Number = "number",
11
- Boolean = "boolean",
12
- Select = "select"
13
- }
14
- declare enum ConfigScope {
15
- Global = "global",
16
- Country = "country"
17
- }
18
- interface SelectOption {
19
- value: string;
20
- label: string;
21
- }
22
- interface PluginConfigFieldDependency {
23
- field: string;
24
- value: string[];
25
- }
26
- interface PluginConfigField {
27
- key: string;
28
- label: string;
29
- type: FieldType;
30
- required: boolean;
31
- scopedTo?: ConfigScope;
32
- dependsOn?: PluginConfigFieldDependency;
33
- placeholder?: string;
34
- description?: string;
35
- options?: SelectOption[];
36
- internal?: boolean;
37
- /** Visual group header rendered above the first field of each new group. */
38
- group?: string;
39
- }
40
-
41
- declare enum FieldVariant {
42
- Text = "text",
43
- Secret = "secret",
44
- Url = "url",
45
- Number = "number",
46
- Select = "select",
47
- Textarea = "textarea",
48
- /**
49
- * Renders a small option set (a `select`-typed schema field) as a segmented
50
- * pill control instead of a dropdown. Purely presentational — the underlying
51
- * value/options come from the referenced configSchema field.
52
- */
53
- Segmented = "segmented"
54
- }
55
- declare enum ActionVariant {
56
- Primary = "primary",
57
- Secondary = "secondary",
58
- Danger = "danger"
59
- }
60
- declare enum RepeaterSource {
61
- SupportedCountries = "supportedCountries"
62
- }
63
- /**
64
- * Presentation mode for the whole layout. Declared by the plugin wins; when
65
- * absent the HOST infers it (wizard when the layout iterates per-country,
66
- * stacked otherwise). Inference is a host concern and is NOT part of this
67
- * contract — the SDK only carries the optional declared value.
68
- */
69
- declare enum LayoutMode {
70
- Wizard = "wizard",
71
- Stacked = "stacked",
72
- Tabs = "tabs",
73
- Sections = "sections"
74
- }
75
- declare enum BlockType {
76
- Field = "field",
77
- Group = "group",
78
- Toggle = "toggle",
79
- Action = "action",
80
- Callout = "callout",
81
- Markdown = "markdown",
82
- Divider = "divider",
83
- Conditional = "conditional",
84
- Repeater = "repeater",
85
- Card = "card",
86
- Banner = "banner",
87
- CopyField = "copyField",
88
- InlineRow = "inlineRow",
89
- Tabs = "tabs",
90
- Accordion = "accordion",
91
- KeyValue = "keyValue"
92
- }
93
- declare enum StepStatusFrom {
94
- Fields = "fields",
95
- Action = "action"
96
- }
97
- /**
98
- * Shared base every block extends. Carries the optional 12-col grid span
99
- * (1–12). Out-of-range values are clamped by the HOST at render time; the
100
- * contract accepts any number so a newer plugin is never bricked by an older
101
- * host.
102
- */
103
- interface BlockBase {
104
- span?: number;
105
- }
106
- interface FieldBlock extends BlockBase {
107
- type: BlockType.Field;
108
- /** References a key in the plugin's configSchema. */
109
- key: string;
110
- variant?: FieldVariant;
111
- /** Override the configSchema label inside this layout. */
112
- labelOverride?: string;
113
- /**
114
- * Name of a `resolveOptions` source. When set, the host resolves the option
115
- * list at runtime via `plugin.resolveOptions(optionsFrom, ctx)` instead of a
116
- * static option set. NOT a configSchema key — it is a runtime source id.
117
- */
118
- optionsFrom?: string;
119
- }
120
- interface GroupBlock extends BlockBase {
121
- type: BlockType.Group;
122
- title: string;
123
- description?: string;
124
- /** configSchema keys included in this group. */
125
- fields: string[];
126
- collapsible?: boolean;
127
- defaultOpen?: boolean;
128
- }
129
- interface ToggleBlock extends BlockBase {
130
- type: BlockType.Toggle;
131
- /** Logical id, not necessarily a config key. */
132
- key: string;
133
- label: string;
134
- description?: string;
135
- }
136
- interface ActionBlock extends BlockBase {
137
- type: BlockType.Action;
138
- /** Matches a manifest.actions[id]. */
139
- id: string;
140
- label: string;
141
- variant?: ActionVariant;
142
- /** When set, the action result feeds the named callout slot. */
143
- resultSlot?: string;
144
- }
145
- interface CalloutBlock extends BlockBase {
146
- type: BlockType.Callout;
147
- variant: MessageVariant;
148
- text: string;
149
- /** Slot id for `action.resultSlot` to write into. */
150
- slot?: string;
151
- }
152
- interface MarkdownBlock extends BlockBase {
153
- type: BlockType.Markdown;
154
- content: string;
155
- }
156
- interface DividerBlock extends BlockBase {
157
- type: BlockType.Divider;
158
- }
159
- type ConditionalEquals = string | number | boolean | null;
160
- interface ConditionalWhen {
161
- key: string;
162
- equals: ConditionalEquals;
163
- }
164
- interface ConditionalBlock extends BlockBase {
165
- type: BlockType.Conditional;
166
- when: ConditionalWhen;
167
- blocks: Block[];
168
- }
169
- interface RepeaterBlock extends BlockBase {
170
- type: BlockType.Repeater;
171
- source: RepeaterSource;
172
- /** Token interpolation: {countryCode}, {countryName}. */
173
- blocks: Block[];
174
- }
175
- /** Titled container. Recurses into `blocks`. */
176
- interface CardBlock extends BlockBase {
177
- type: BlockType.Card;
178
- title?: string;
179
- description?: string;
180
- blocks: Block[];
181
- }
182
- /** Prominent variant-styled message. Leaf. */
183
- interface BannerBlock extends BlockBase {
184
- type: BlockType.Banner;
185
- variant: MessageVariant;
186
- title?: string;
187
- text: string;
188
- }
189
- /**
190
- * Read-only value with a copy affordance. EXACTLY ONE source of the value:
191
- * a literal, a host `computedValues` key, or a read-only echo of a config key.
192
- */
193
- interface CopyFieldBlock extends BlockBase {
194
- type: BlockType.CopyField;
195
- label: string;
196
- /** Literal value. */
197
- value?: string;
198
- /** Key into the host-provided `computedValues` map. */
199
- computedKey?: string;
200
- /** Read-only echo of a configSchema field value. */
201
- fieldKey?: string;
202
- }
203
- /** Horizontal row on wide viewports, stacks on narrow. Recurses. */
204
- interface InlineRowBlock extends BlockBase {
205
- type: BlockType.InlineRow;
206
- blocks: Block[];
207
- }
208
- interface TabItem {
209
- id: string;
210
- label: string;
211
- blocks: Block[];
212
- }
213
- /** One panel visible at a time. Recurses per tab. */
214
- interface TabsBlock extends BlockBase {
215
- type: BlockType.Tabs;
216
- tabs: TabItem[];
217
- }
218
- interface AccordionSection {
219
- id: string;
220
- title: string;
221
- defaultOpen?: boolean;
222
- blocks: Block[];
223
- }
224
- /** Collapsible sections. Local toggle, not persisted. Recurses per section. */
225
- interface AccordionBlock extends BlockBase {
226
- type: BlockType.Accordion;
227
- sections: AccordionSection[];
228
- }
229
- interface KeyValueRow {
230
- label: string;
231
- value?: string;
232
- computedKey?: string;
233
- }
234
- /** Read-only label/value list. Leaf. */
235
- interface KeyValueBlock extends BlockBase {
236
- type: BlockType.KeyValue;
237
- rows: KeyValueRow[];
238
- }
239
- type Block = FieldBlock | GroupBlock | ToggleBlock | ActionBlock | CalloutBlock | MarkdownBlock | DividerBlock | ConditionalBlock | RepeaterBlock | CardBlock | BannerBlock | CopyFieldBlock | InlineRowBlock | TabsBlock | AccordionBlock | KeyValueBlock;
240
- interface StepStatusFromFields {
241
- from: StepStatusFrom.Fields;
242
- }
243
- interface StepStatusFromAction {
244
- from: StepStatusFrom.Action;
245
- actionId: string;
246
- }
247
- type StepStatusSource = StepStatusFromFields | StepStatusFromAction;
248
- interface SetupStep {
249
- id: string;
250
- title: string;
251
- intro?: string;
252
- blocks: Block[];
253
- /** When set, the step renders once per item of the source. */
254
- repeatFor?: RepeaterSource;
255
- status?: StepStatusSource;
256
- }
257
- interface SetupAction {
258
- id: string;
259
- /** Optional human label (admin can render in audit logs). */
260
- label?: string;
261
- /** Whether the action runs per-country. Default: false. */
262
- perCountry?: boolean;
263
- }
264
- interface SetupLayout {
265
- /** Reserved for Phase 2 — points to a plugin-shipped React bundle. */
266
- customScreen?: string;
267
- /**
268
- * Presentation mode. Declared wins; when absent the host infers it. Additive
269
- * in 0.4.0 — an older host ignores it and keeps its inferred layout.
270
- */
271
- mode?: LayoutMode;
272
- intro?: string;
273
- steps: SetupStep[];
274
- actions?: SetupAction[];
275
- }
276
-
277
- interface SetupLayoutValidation {
278
- success: boolean;
279
- data?: SetupLayout;
280
- errors?: string[];
281
- }
282
- /** Validates the full layout including recursive blocks. */
283
- declare function validateSetupLayout(input: unknown): SetupLayoutValidation;
284
- declare function crossValidateSetupLayout(layout: SetupLayout, configSchema: PluginConfigField[]): string[];
285
-
286
- interface PluginManifest {
287
- name: string;
288
- displayName?: string;
289
- version: string;
290
- entry: string;
291
- type?: PluginType;
292
- icon?: string;
293
- description?: string;
294
- dependencies?: string[];
295
- /** Minimum @vivoa/store host version this plugin runs on (semver). */
296
- minHostVersion?: string;
297
- /**
298
- * SDK contract version the plugin was compiled against (see SDK_VERSION).
299
- * Hosts refuse plugins with an incompatible contract via isSdkCompatible.
300
- */
301
- sdkVersion?: string;
302
- /**
303
- * Declarative admin setup screen. When omitted, host renders the legacy
304
- * auto-form derived from the plugin's configSchema.
305
- */
306
- setup?: SetupLayout;
307
- }
308
-
309
- declare enum PluginType {
310
- Payment = "payment",
311
- Shipping = "shipping",
312
- Analytics = "analytics",
313
- Generic = "generic"
314
- }
315
- /** Visual tone for messages, callouts and action results. */
316
- declare enum MessageVariant {
317
- Info = "info",
318
- Warning = "warning",
319
- Success = "success",
320
- Danger = "danger"
321
- }
322
- interface PluginActionResult {
323
- ok: boolean;
324
- message?: string;
325
- variant?: MessageVariant;
326
- data?: unknown;
327
- }
328
- interface PluginActionContext {
329
- /** When the action was triggered from a country-scoped step. */
330
- country?: string;
331
- /** Free-form payload sent from the admin UI. */
332
- payload?: unknown;
333
- /**
334
- * Resolved GLOBAL-scope config for the current tenant. The host populates
335
- * this so actions (e.g. testConnection) can build a client without any
336
- * prior `initialize()` — same stateless discipline as the dispatch methods.
337
- */
338
- config?: Record<string, unknown>;
339
- /** Resolved config for `country`, when the action is country-scoped. */
340
- countryConfig?: Record<string, unknown>;
341
- }
342
- /** Option resolved at runtime for a field whose `optionsFrom` is set. */
343
- interface FieldOption {
344
- value: string;
345
- label: string;
346
- }
347
- interface IPlugin {
348
- readonly manifest: PluginManifest;
349
- onActivate?(): Promise<void>;
350
- onDeactivate?(): Promise<void>;
351
- invokeAction?(actionId: string, ctx: PluginActionContext): Promise<PluginActionResult>;
352
- /**
353
- * Resolve the option list for a field whose `optionsFrom` matches `source`.
354
- * PURE (query semantics) — the host never persists anything as a side effect
355
- * of calling it. Optional: a plugin without it degrades the field to a plain
356
- * input. Draft-aware via `ctx` (same resolved-config discipline as
357
- * `invokeAction`).
358
- */
359
- resolveOptions?(source: string, ctx: PluginActionContext): Promise<FieldOption[]>;
360
- }
361
- interface ConfigurablePlugin {
362
- loadConfig(config: Record<string, unknown>): void;
363
- }
364
- declare function isConfigurablePlugin(plugin: unknown): plugin is ConfigurablePlugin;
8
+ declare const INVOICING_PLUGIN_TOKEN: "INVOICING_PLUGINS";
365
9
 
366
10
  interface FieldDependsOn {
367
11
  field: string;
@@ -392,808 +36,6 @@ interface PluginConfigResult {
392
36
  }
393
37
  declare function createPluginConfig(fields: FieldMap): PluginConfigResult;
394
38
 
395
- /**
396
- * Everything a plugin needs to serve ONE operation for ONE tenant, resolved by
397
- * the host up front. Nothing here is cached on the plugin instance — the same
398
- * plugin object serves every tenant, and each call carries its own context.
399
- * This is what removes the "init + dispatch in the same synchronous block"
400
- * hazard the stateful contract used to require.
401
- */
402
- interface DispatchContext {
403
- /** Resolved, merged GLOBAL-scope config for the current tenant. */
404
- readonly config: Record<string, unknown>;
405
- /**
406
- * Resolved config for the country in scope, when the operation is
407
- * country-bound (e.g. a shipping quote for SV). Merged defaults + tenant DB.
408
- */
409
- readonly countryConfig?: Record<string, unknown>;
410
- /**
411
- * All resolved country configs keyed by ISO code, for operations that span
412
- * countries. Prefer {@link countryConfig} for single-country dispatch.
413
- */
414
- readonly countryConfigs?: Record<string, Record<string, unknown>>;
415
- /** The ISO country code in scope, when applicable. */
416
- readonly countryCode?: string;
417
- }
418
-
419
- /**
420
- * Free-form gateway code defined by each plugin in its manifest/config.
421
- * The host stores this string verbatim; no enum of allowed providers.
422
- */
423
- type PaymentGatewayCode = string;
424
- declare enum TransactionStatus {
425
- Pending = "Pending",
426
- PendingRedirect = "Pending_Redirect",
427
- Approved = "Approved",
428
- Declined = "Declined",
429
- Failed = "Failed",
430
- Error = "Error"
431
- }
432
- declare enum GatewayEnvironment {
433
- Sandbox = "sandbox",
434
- Production = "production"
435
- }
436
- interface PaymentCard {
437
- number: string;
438
- cvv: string;
439
- expirationMonth: string;
440
- expirationYear: string;
441
- holderFirstName: string;
442
- holderLastName: string;
443
- }
444
- interface PaymentCustomer {
445
- email: string;
446
- phone: string;
447
- address?: string;
448
- city?: string;
449
- state?: string;
450
- country?: string;
451
- zip?: string;
452
- }
453
- interface PaymentPayload {
454
- amount: number;
455
- currency: string;
456
- orderId: string;
457
- card: PaymentCard;
458
- customer: PaymentCustomer;
459
- }
460
- /**
461
- * Generic verify payload. Provider-specific data travels in `providerData`,
462
- * each plugin casts it to its own type. The host passes it through opaquely.
463
- */
464
- interface PaymentVerifyPayload {
465
- transactionId: string;
466
- providerData?: unknown;
467
- }
468
- interface PaymentResult {
469
- status: TransactionStatus;
470
- gatewayTransactionId: string;
471
- message: string;
472
- authorizationCode?: string;
473
- redirectUrl?: string;
474
- rawResponse?: unknown;
475
- }
476
- /**
477
- * How the host should render the payment step for this gateway.
478
- * - `card-in` host-owned card form, charged via `processPayment` (default).
479
- * - `offsite-redirect` host sends the shopper to `redirectUrl`.
480
- * - `embed` gateway-owned iframe initialised via `createPaymentSession`.
481
- */
482
- type PaymentRenderMode = 'card-in' | 'offsite-redirect' | 'embed';
483
- interface GatewayStaticConfig {
484
- code: PaymentGatewayCode;
485
- displayName: string;
486
- description: string;
487
- environment: GatewayEnvironment;
488
- supportedMethods: string[];
489
- requiredEnvVars: string[];
490
- /**
491
- * OPTIONAL render mode. Absent ⇒ host treats the gateway as `'card-in'`.
492
- * Back-compat: existing card-in plugins (Wompi/Serfinsa) omit this field.
493
- */
494
- renderMode?: PaymentRenderMode;
495
- }
496
- /**
497
- * Cardless payload for creating a gateway-hosted payment session (INV-1).
498
- * Used by `embed` / `offsite-redirect` gateways where the host never touches
499
- * card data — the shopper enters it inside the gateway's own surface.
500
- */
501
- interface PaymentSessionPayload {
502
- /**
503
- * Charge amount in DECIMAL major units, 2 decimal places (e.g. `12.34`).
504
- * Matches Boxful `@boxful/contracts` `getTwoDecimals` / `toFixed(2)`.
505
- */
506
- amount: number;
507
- currency: string;
508
- orderId: string;
509
- customer: PaymentCustomer;
510
- /** Optional display/reconciliation hints shown on the gateway surface. */
511
- orderSummary?: {
512
- description?: string;
513
- merchant?: string;
514
- reference?: string;
515
- };
516
- }
517
- /**
518
- * Everything the host needs to mount a gateway-owned payment iframe.
519
- * `sessionToken` is OPAQUE to the host; the amount is sealed server-side by the
520
- * gateway, so the host cannot tamper with it.
521
- */
522
- interface EmbedInit {
523
- sessionToken: string;
524
- iframeUrl: string;
525
- allowedOrigins: string[];
526
- /** Expiry as epoch SECONDS. Owner TTL guidance: 15 minutes. */
527
- expiresAt?: number;
528
- }
529
- /**
530
- * Result of `createPaymentSession`. `embedInit` is present iff
531
- * `renderMode === 'embed'`; `redirectUrl` iff `renderMode === 'offsite-redirect'`.
532
- */
533
- interface PaymentSessionResult {
534
- renderMode: PaymentRenderMode;
535
- embedInit?: EmbedInit;
536
- redirectUrl?: string;
537
- }
538
- interface PaymentPluginConfig {
539
- configSchema: PluginConfigField[];
540
- }
541
- interface WebhookSignatureResult {
542
- isValid: boolean;
543
- error?: string;
544
- }
545
- interface IPaymentPlugin extends IPlugin {
546
- readonly gatewayCode: PaymentGatewayCode;
547
- readonly staticConfig: GatewayStaticConfig;
548
- readonly paymentConfig?: PaymentPluginConfig;
549
- processPayment(payload: PaymentPayload, ctx: DispatchContext): Promise<PaymentResult>;
550
- verifyTransaction?(payload: PaymentVerifyPayload, ctx: DispatchContext): Promise<PaymentResult>;
551
- validateWebhookSignature?(rawBody: string | Buffer, headers: Record<string, string>, ctx: DispatchContext): WebhookSignatureResult;
552
- processWebhook?(payload: unknown, ctx: DispatchContext): Promise<void>;
553
- /**
554
- * Query the gateway for the current status of a previously attempted charge.
555
- * Called by the host when `processPayment` returns `status: Error` with a
556
- * non-empty `gatewayTransactionId` (e.g. Serfinsa `audit_no` on timeout).
557
- * MUST NOT accept or re-use card data — ID-only reconciliation.
558
- */
559
- queryTransaction?(ref: {
560
- transactionId: string;
561
- }, ctx: DispatchContext): Promise<PaymentResult>;
562
- /**
563
- * Create a gateway-hosted payment session for `embed` / `offsite-redirect`
564
- * render modes. OPTIONAL — `card-in` plugins never implement it and charge
565
- * via `processPayment` instead. STATELESS: gateway credentials arrive per
566
- * call via `ctx.config` (INV-4); no card data is ever passed here (INV-1).
567
- */
568
- createPaymentSession?(payload: PaymentSessionPayload, ctx: DispatchContext): Promise<PaymentSessionResult>;
569
- }
570
-
571
- declare enum ShippingFeature {
572
- Tracking = "tracking",
573
- Cod = "cod",
574
- Quotes = "quotes",
575
- Labels = "labels",
576
- /**
577
- * The carrier pushes shipment status changes to a registered webhook URL,
578
- * and the plugin can normalize + authenticate that payload via
579
- * {@link IShippingPlugin.parseWebhook}. Enables unattended order transitions
580
- * (e.g. → delivered) instead of manual admin updates.
581
- */
582
- TrackingSync = "tracking-sync"
583
- }
584
- declare enum CodFeeType {
585
- Percentage = "percentage",
586
- Fixed = "fixed"
587
- }
588
- interface CodFeeConfig {
589
- type: CodFeeType;
590
- value: number;
591
- description: string;
592
- }
593
- interface ShippingDefaultConfig {
594
- global?: Record<string, unknown>;
595
- countries?: Record<string, Record<string, unknown>>;
596
- }
597
- interface ShippingPluginConfig {
598
- supportedCountries: string[];
599
- supportedFeatures: ShippingFeature[];
600
- configSchema: PluginConfigField[];
601
- codFeeConfig?: CodFeeConfig;
602
- defaultConfig?: ShippingDefaultConfig;
603
- }
604
- interface ShippingStaticConfig {
605
- code: string;
606
- displayName: string;
607
- description: string;
608
- iconUrl?: string;
609
- supportedCountries: string[];
610
- supportedFeatures: ShippingFeature[];
611
- configSchema: PluginConfigField[];
612
- codFeeConfig?: CodFeeConfig;
613
- }
614
- interface ShipmentAddress {
615
- fullName: string;
616
- phone: string;
617
- phoneAreaCode: string;
618
- email: string | null;
619
- address: string;
620
- referencePoint: string;
621
- instructions?: string;
622
- city: string;
623
- cityId?: string;
624
- state: string;
625
- stateId?: string;
626
- zip?: string;
627
- country: string;
628
- latitude?: number;
629
- longitude?: number;
630
- }
631
- interface ShipmentParcel {
632
- content: string;
633
- length: number;
634
- width: number;
635
- height: number;
636
- weight: number;
637
- price?: number;
638
- isFragile?: boolean;
639
- }
640
- interface ShippingQuoteParams {
641
- origin: ShipmentAddress;
642
- destination: ShipmentAddress;
643
- countryCode: string;
644
- parcels?: ShipmentParcel[];
645
- }
646
- interface ShippingQuote {
647
- carrierId: string;
648
- carrierName: string;
649
- price: number;
650
- codCommission: number;
651
- codFee?: number;
652
- supportsCod: boolean;
653
- deliveryType: string;
654
- logo: string | null;
655
- isPricePromotion: boolean;
656
- isCommissionPromotion: boolean;
657
- provider: string;
658
- }
659
- interface CodConfig {
660
- enabled: boolean;
661
- amount: number;
662
- }
663
- interface CreateShipmentParams {
664
- orderId: string;
665
- pickup: ShipmentAddress;
666
- delivery: ShipmentAddress;
667
- parcels: ShipmentParcel[];
668
- recolectionDate: Date;
669
- cod?: CodConfig;
670
- courierId?: string;
671
- serviceLevelToken?: string;
672
- }
673
- interface ShipmentResult {
674
- externalId: string;
675
- trackingNumber: string;
676
- trackingUrl: string;
677
- labelUrl: string | null;
678
- provider: string;
679
- courierName: string;
680
- status: string;
681
- rawResponse?: Record<string, unknown>;
682
- }
683
- /**
684
- * Normalized, carrier-agnostic shipment status event produced by
685
- * {@link IShippingPlugin.parseWebhook}. The host matches `trackingNumber`
686
- * against its stored shipment to resolve the order, so the plugin never needs
687
- * host identifiers. `status: 'unknown'` is a first-class value for carrier
688
- * states the plugin does not map — the host treats it as a no-op instead of
689
- * guessing a transition.
690
- */
691
- interface TrackingEvent {
692
- trackingNumber: string;
693
- status: 'in_transit' | 'delivered' | 'cancelled' | 'unknown';
694
- /** ISO-8601 instant the carrier reported the change, when available. */
695
- occurredAt?: string;
696
- /** Human-readable carrier status, for audit/logging. */
697
- statusDescription?: string;
698
- /** Untouched carrier payload, for diagnostics. Never trusted for control flow. */
699
- raw?: unknown;
700
- }
701
- interface IShippingPlugin extends IPlugin {
702
- readonly name: string;
703
- readonly shippingConfig: ShippingPluginConfig;
704
- createShipment(params: CreateShipmentParams, ctx: DispatchContext): Promise<ShipmentResult>;
705
- getQuotes?(params: ShippingQuoteParams, ctx: DispatchContext): Promise<ShippingQuote[]>;
706
- /** Pure — a tracking URL never depends on tenant config. */
707
- getTrackingUrl(trackingNumber: string): string;
708
- parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): TrackingEvent | null;
709
- isConfigured?(ctx: DispatchContext): boolean;
710
- }
711
-
712
- declare enum SuppliersFeature {
713
- /** Browse/search the supplier catalog. */
714
- CatalogSearch = "catalog-search",
715
- /** Pull a full listing snapshot to seed a native product. */
716
- CatalogImport = "catalog-import",
717
- /** Place + track orders against the supplier. */
718
- Orders = "orders",
719
- /** Supplier pushes order status to a registered webhook. */
720
- FulfillmentSync = "fulfillment-sync",
721
- /**
722
- * Poll the supplier for stock levels. SoyDrop has no inventory webhook, so
723
- * stock is reconciled by polling rather than push.
724
- */
725
- StockSync = "stock-sync"
726
- }
727
- /**
728
- * ISO-4217 money in minor units — mirrors the store's Money VO
729
- * (`core/source/contracts/source-dtos.ts`) so the host maps 1:1 without a
730
- * currency guess. Kept local so the SDK stays dependency-free.
731
- */
732
- interface SupplierMoney {
733
- amountMinor: number;
734
- currency: string;
735
- }
736
- interface SuppliersDefaultConfig {
737
- global?: Record<string, unknown>;
738
- countries?: Record<string, Record<string, unknown>>;
739
- }
740
- interface SuppliersPluginConfig {
741
- supportedCountries: string[];
742
- supportedCapabilities: SuppliersFeature[];
743
- configSchema: PluginConfigField[];
744
- defaultConfig?: SuppliersDefaultConfig;
745
- }
746
- interface SuppliersStaticConfig {
747
- code: string;
748
- displayName: string;
749
- description: string;
750
- iconUrl?: string;
751
- supportedCountries: string[];
752
- supportedCapabilities: SuppliersFeature[];
753
- configSchema: PluginConfigField[];
754
- }
755
- interface SupplierCatalogQuery {
756
- text?: string;
757
- country?: string;
758
- cursor?: string;
759
- limit?: number;
760
- }
761
- interface SupplierListingVariant {
762
- externalVariantId: string;
763
- sku?: string | null;
764
- title: string;
765
- wholesalePrice: SupplierMoney;
766
- options?: Record<string, string>;
767
- imageUrl?: string | null;
768
- available?: boolean;
769
- }
770
- interface SupplierListingAttribute {
771
- name: string;
772
- value: string;
773
- }
774
- interface SupplierStock {
775
- externalId: string;
776
- quantity: number;
777
- inStock: boolean;
778
- }
779
- interface SupplierListing {
780
- /** Native id in the supplier catalog (product or catalog-item id). */
781
- externalId: string;
782
- title: string;
783
- description?: string | null;
784
- sku?: string | null;
785
- /** ABSOLUTE image URLs. `imageUrl` is the primary; `images` the gallery. */
786
- imageUrl?: string | null;
787
- images?: string[];
788
- /** Wholesale cost the merchant pays the supplier (per unit). */
789
- wholesalePrice: SupplierMoney;
790
- /** Supplier's suggested retail, when provided. */
791
- suggestedPrice?: SupplierMoney | null;
792
- stock: SupplierStock;
793
- categories?: string[];
794
- attributes?: SupplierListingAttribute[];
795
- hasVariants: boolean;
796
- variants?: SupplierListingVariant[];
797
- moq?: number | null;
798
- /** Untouched supplier payload, for diagnostics. Never trusted for control flow. */
799
- raw?: unknown;
800
- }
801
- interface SupplierListingPage {
802
- items: SupplierListing[];
803
- nextCursor?: string | null;
804
- }
805
- interface SupplierOrderCustomer {
806
- name: string;
807
- lastName?: string | null;
808
- phoneAreaCode: string;
809
- phone: string;
810
- email?: string | null;
811
- }
812
- interface SupplierOrderAddressLevel {
813
- levelKey: string;
814
- valueId: string;
815
- }
816
- interface SupplierShipTo {
817
- address: string;
818
- referencePoint?: string | null;
819
- /**
820
- * Supplier-native geo ids. Optional: when the host cannot produce the
821
- * supplier's own ids (the common case — the host only knows its own geo),
822
- * it leaves these empty and passes the human-readable names below. The
823
- * plugin resolves names → supplier ids against its own geo endpoints.
824
- */
825
- stateId?: string;
826
- cityId?: string;
827
- /** ISO 3166-1 alpha-2 of the destination country (e.g. "GT", "SV"). */
828
- countryCode?: string;
829
- /** Human-readable admin-area (state/department) name for plugin-side resolution. */
830
- stateName?: string;
831
- /** Human-readable locality (city/municipality) name for plugin-side resolution. */
832
- cityName?: string;
833
- extraLevels?: SupplierOrderAddressLevel[];
834
- latitude?: number;
835
- longitude?: number;
836
- instructions?: string | null;
837
- }
838
- interface SupplierOrderLine {
839
- /** Supplier catalog/variant id to order. */
840
- externalListingId: string;
841
- quantity: number;
842
- /** Optional price override; omit to use the supplier's catalog price. */
843
- unitPrice?: SupplierMoney | null;
844
- }
845
- interface PlaceSupplierOrderInput {
846
- /** Host order id — the idempotency key the supplier dedupes on. */
847
- externalOrderId: string;
848
- customer: SupplierOrderCustomer;
849
- shipTo: SupplierShipTo;
850
- lines: SupplierOrderLine[];
851
- cod: boolean;
852
- /** Exact amount to collect on COD; defaults to the line total. */
853
- codAmount?: SupplierMoney | null;
854
- /** Optional carrier choice; the supplier picks a default when omitted. */
855
- courierId?: string | null;
856
- note?: string | null;
857
- }
858
- /**
859
- * Normalized supplier-order status. `unknown` is a first-class value for
860
- * supplier states the adapter does not map — the host treats it as a no-op.
861
- */
862
- type SupplierOrderStatus = 'pending' | 'accepted' | 'in_transit' | 'shipped' | 'delivered' | 'cancelled' | 'rejected' | 'unknown';
863
- interface SupplierOrderResult {
864
- /** Supplier-side order id. */
865
- externalId: string;
866
- orderNumber?: string | null;
867
- /** The host order id echoed back, when the supplier stores it. */
868
- externalOrderId?: string | null;
869
- status: SupplierOrderStatus;
870
- statusLabel?: string | null;
871
- trackingCode?: string | null;
872
- trackingUrl?: string | null;
873
- carrier?: string | null;
874
- shippingCost?: SupplierMoney | null;
875
- codAmount?: SupplierMoney | null;
876
- raw?: unknown;
877
- }
878
- /**
879
- * Normalized, supplier-agnostic fulfillment event produced by
880
- * {@link ISuppliersPlugin.parseWebhook}. The host matches `externalOrderId`
881
- * against its stored SupplierOrder to resolve the local order, so the adapter
882
- * never needs host identifiers.
883
- */
884
- interface SupplierFulfillmentEvent {
885
- externalOrderId: string;
886
- status: SupplierOrderStatus;
887
- trackingCode?: string | null;
888
- carrier?: string | null;
889
- /** ISO-8601 instant the supplier reported the change, when available. */
890
- occurredAt?: string;
891
- statusDescription?: string;
892
- /** Untouched supplier payload, for diagnostics. */
893
- raw?: unknown;
894
- }
895
- interface ISuppliersPlugin extends IPlugin {
896
- readonly name: string;
897
- readonly suppliersConfig: SuppliersPluginConfig;
898
- searchCatalog(query: SupplierCatalogQuery, ctx: DispatchContext): Promise<SupplierListingPage>;
899
- getListing(externalId: string, ctx: DispatchContext): Promise<SupplierListing>;
900
- placeOrder(order: PlaceSupplierOrderInput, ctx: DispatchContext): Promise<SupplierOrderResult>;
901
- getOrderStatus(externalOrderId: string, ctx: DispatchContext): Promise<SupplierOrderResult>;
902
- cancelOrder?(externalOrderId: string, ctx: DispatchContext): Promise<SupplierOrderResult>;
903
- syncStock?(externalIds: string[], ctx: DispatchContext): Promise<SupplierStock[]>;
904
- parseWebhook?(body: unknown, headers: Record<string, string>, ctx: DispatchContext): SupplierFulfillmentEvent | null;
905
- isConfigured?(ctx: DispatchContext): boolean;
906
- }
907
-
908
- declare enum AnalyticsFeature {
909
- /** Ecommerce funnel events: view_item, add_to_cart, begin_checkout, purchase. */
910
- Ecommerce = "ecommerce",
911
- /** Generic page_view tracking. */
912
- PageViews = "page-views"
913
- }
914
- /**
915
- * ISO-4217 money in minor units — mirrors the store's Money VO so the host maps
916
- * 1:1 without a currency guess. Kept local so the SDK stays dependency-free.
917
- */
918
- interface AnalyticsMoney {
919
- amountMinor: number;
920
- currency: string;
921
- }
922
- /** A single line item attached to an ecommerce event. */
923
- interface AnalyticsItem {
924
- /** Product id as the store knows it (Meta `content_ids`, GA4 `item_id`). */
925
- id: string;
926
- /** Variant id for catalog-level granularity, when the line resolves one. */
927
- variantId?: string | null;
928
- name?: string;
929
- sku?: string | null;
930
- /** Brand for catalog feeds that key on it. */
931
- brand?: string | null;
932
- quantity?: number;
933
- price?: AnalyticsMoney;
934
- category?: string | null;
935
- }
936
- /**
937
- * Canonical, provider-agnostic event names the host emits. Closed set: the host
938
- * only ever maps a domain event to one of these. An adapter that does not care
939
- * about a given name simply ignores it.
940
- */
941
- type AnalyticsEventName = 'page_view' | 'view_item' | 'add_to_cart' | 'remove_from_cart' | 'begin_checkout' | 'purchase';
942
- /**
943
- * Where the action physically happened. Maps to Meta `action_source`; other
944
- * providers ignore it. Defaults to `website` when the host omits it.
945
- */
946
- type AnalyticsActionSource = 'website' | 'app' | 'server' | 'phone_call' | 'chat' | 'email' | 'physical_store' | 'other';
947
- /**
948
- * Identity + match-quality signals. EVERYTHING here is optional — the host
949
- * populates whatever it can resolve for the event in scope.
950
- *
951
- * @rule The `*Sha256` fields arrive ALREADY hashed by the host (SHA256 hex of
952
- * the normalized value: lowercased + trimmed; phone in E.164 digits).
953
- * The plugin NEVER receives raw PII. `externalId`, `clientIpAddress`,
954
- * `clientUserAgent` and the click ids are the exception — providers
955
- * require them PLAIN.
956
- */
957
- interface AnalyticsUserData {
958
- emailSha256?: string | null;
959
- phoneSha256?: string | null;
960
- firstNameSha256?: string | null;
961
- lastNameSha256?: string | null;
962
- citySha256?: string | null;
963
- stateSha256?: string | null;
964
- zipSha256?: string | null;
965
- countrySha256?: string | null;
966
- genderSha256?: string | null;
967
- /** Date of birth, YYYYMMDD normalized then SHA256. */
968
- dobSha256?: string | null;
969
- /** Store customer/user id — Meta `external_id` (not hashed by spec). */
970
- externalId?: string | null;
971
- /** Plain IPv4/IPv6 — never hashed (geo match). */
972
- clientIpAddress?: string | null;
973
- /** Plain browser UA — never hashed (device match). */
974
- clientUserAgent?: string | null;
975
- /** Meta browser cookie `_fbp`. */
976
- fbp?: string | null;
977
- /** Meta click id `_fbc`. */
978
- fbc?: string | null;
979
- /** Google Ads click id. */
980
- gclid?: string | null;
981
- /** TikTok click id. */
982
- ttclid?: string | null;
983
- }
984
- /** Marketing attribution captured at the session that led to the event. */
985
- interface AnalyticsUtm {
986
- source?: string | null;
987
- medium?: string | null;
988
- campaign?: string | null;
989
- term?: string | null;
990
- content?: string | null;
991
- }
992
- /**
993
- * Consent signals the host resolved for this event. Providers that honor
994
- * consent (Meta LDU, Google Consent Mode) gate on it; others ignore it.
995
- */
996
- interface AnalyticsConsent {
997
- adStorage?: boolean;
998
- adUserData?: boolean;
999
- adPersonalization?: boolean;
1000
- }
1001
- /**
1002
- * Normalized analytics event. The host builds this from a DomainEvent and hands
1003
- * it to every active analytics adapter. The adapter translates it to its own
1004
- * wire format (GA4 event, Meta event, ...). See the @rule SUPERSET note at the
1005
- * top of the module: this is the superset of what Meta CAPI needs.
1006
- */
1007
- interface AnalyticsEvent {
1008
- name: AnalyticsEventName;
1009
- /** ISO-8601 instant the underlying action happened. */
1010
- occurredAt: string;
1011
- /**
1012
- * Stable id for cross-channel deduplication against the browser pixel (Meta
1013
- * `event_id`). For `purchase` the host sets it to the order id so the pixel
1014
- * and the server event collapse into one.
1015
- */
1016
- eventId?: string | null;
1017
- /** Where the action happened — Meta `action_source`. Defaults to `website`. */
1018
- actionSource?: AnalyticsActionSource;
1019
- /**
1020
- * Pseudonymous client identity for sessionization (maps to GA4 `client_id`
1021
- * / Meta `external_id`). Null when the host cannot resolve a stable id.
1022
- */
1023
- clientId?: string | null;
1024
- sessionId?: string | null;
1025
- /** Hashed identity + client signals + click ids. See {@link AnalyticsUserData}. */
1026
- user?: AnalyticsUserData;
1027
- /** Monetary value for value-bearing events (purchase, begin_checkout). */
1028
- value?: AnalyticsMoney | null;
1029
- /** Order id for `purchase` — providers dedupe transactions on it. */
1030
- transactionId?: string | null;
1031
- items?: AnalyticsItem[];
1032
- /** Page context for `page_view`. */
1033
- pageLocation?: string | null;
1034
- /** Referring URL, when the host knows it. */
1035
- pageReferrer?: string | null;
1036
- pageTitle?: string | null;
1037
- /** Marketing attribution for the session that produced the event. */
1038
- utm?: AnalyticsUtm;
1039
- /** Consent signals resolved by the host for this event. */
1040
- consent?: AnalyticsConsent;
1041
- /** Extra params forwarded verbatim as custom dimensions. */
1042
- params?: Record<string, unknown>;
1043
- }
1044
- interface AnalyticsPluginConfig {
1045
- supportedCapabilities: AnalyticsFeature[];
1046
- configSchema: PluginConfigField[];
1047
- /** GLOBAL-scope defaults merged under the tenant DB config by the host. */
1048
- defaultConfig?: Record<string, unknown>;
1049
- }
1050
- interface AnalyticsStaticConfig {
1051
- code: string;
1052
- displayName: string;
1053
- description: string;
1054
- iconUrl?: string;
1055
- supportedCapabilities: AnalyticsFeature[];
1056
- configSchema: PluginConfigField[];
1057
- }
1058
- interface IAnalyticsPlugin extends IPlugin {
1059
- readonly name: string;
1060
- readonly analyticsConfig: AnalyticsPluginConfig;
1061
- /**
1062
- * Forward one canonical event to the provider's ingestion API. Stateless: the
1063
- * tenant's resolved credentials arrive in `ctx.config` on every call.
1064
- *
1065
- * @rule BEST-EFFORT — never throw on a transport/provider error. Analytics is
1066
- * fire-and-forget and MUST NOT break the domain flow that triggered it.
1067
- */
1068
- track(event: AnalyticsEvent, ctx: DispatchContext): Promise<void>;
1069
- /**
1070
- * Optional readiness probe. Availability = enabled AND isConfigured.
1071
- * @compat When omitted, the host assumes the adapter is ready.
1072
- */
1073
- isConfigured?(ctx: DispatchContext): boolean;
1074
- }
1075
-
1076
- /** A named unit of behaviour a plugin exposes to the host registry. */
1077
- interface Capability<T = unknown> {
1078
- kind: string;
1079
- impl: T;
1080
- }
1081
- /**
1082
- * Canonical built-in capability kinds. Open set — a plugin MAY register a
1083
- * `kind` not listed here; the host routes by string. These constants exist so
1084
- * first-party contracts share one spelling.
1085
- */
1086
- declare const CapabilityKind: {
1087
- readonly Payment: "payment";
1088
- readonly Shipping: "shipping";
1089
- readonly Suppliers: "suppliers";
1090
- readonly Analytics: "analytics";
1091
- };
1092
- type CapabilityKind = (typeof CapabilityKind)[keyof typeof CapabilityKind];
1093
- declare function capability<T>(kind: string, impl: T): Capability<T>;
1094
- declare function paymentCapability(impl: IPaymentPlugin): Capability<IPaymentPlugin>;
1095
- declare function shippingCapability(impl: IShippingPlugin): Capability<IShippingPlugin>;
1096
- declare function suppliersCapability(impl: ISuppliersPlugin): Capability<ISuppliersPlugin>;
1097
- declare function analyticsCapability(impl: IAnalyticsPlugin): Capability<IAnalyticsPlugin>;
1098
- /**
1099
- * A constructed plugin. `capabilities` is the static declaration the host reads
1100
- * up front; `onActivate` runs when the host mounts the plugin for a tenant and
1101
- * is where side-effecting registration/subscription happens.
1102
- */
1103
- interface Plugin {
1104
- readonly manifest: PluginManifest;
1105
- readonly capabilities: Capability[];
1106
- onActivate?(host: HostApi): void | Promise<void>;
1107
- onDeactivate?(): void | Promise<void>;
1108
- }
1109
- /**
1110
- * The plugin entry point. The compiled bundle's default export is a
1111
- * `PluginFactory`; the host calls it with a per-tenant `HostApi`. No NestJS,
1112
- * no decorators — the host owns dependency injection on its side.
1113
- */
1114
- type PluginFactory = (host: HostApi) => Plugin | Promise<Plugin>;
1115
- /**
1116
- * Anchors the factory type for plugin authors AND brands the function so the
1117
- * host loader can tell a `PluginFactory` (new, framework-agnostic) apart from a
1118
- * legacy NestJS `@Module` default export at runtime.
1119
- */
1120
- declare function definePlugin(factory: PluginFactory): PluginFactory;
1121
- /** True when `value` was produced by {@link definePlugin}. */
1122
- declare function isPluginFactory(value: unknown): value is PluginFactory;
1123
-
1124
- interface Logger {
1125
- debug(message: string, ...meta: unknown[]): void;
1126
- info(message: string, ...meta: unknown[]): void;
1127
- warn(message: string, ...meta: unknown[]): void;
1128
- error(message: string, ...meta: unknown[]): void;
1129
- }
1130
- interface HttpRequest {
1131
- method: string;
1132
- url: string;
1133
- headers?: Record<string, string>;
1134
- body?: unknown;
1135
- }
1136
- interface HttpResponse {
1137
- status: number;
1138
- headers: Record<string, string>;
1139
- body: unknown;
1140
- }
1141
- /**
1142
- * Outbound HTTP mediated by the host. The host enforces the plugin's
1143
- * `http.outbound:<host>` permissions before the request leaves the process —
1144
- * the plugin cannot reach the network directly.
1145
- */
1146
- interface HttpClient {
1147
- request(req: HttpRequest): Promise<HttpResponse>;
1148
- }
1149
- /**
1150
- * Secret access mediated by the host (never `process.env` directly). Gated by
1151
- * `secrets.read:<key>` permissions. Returns the resolved per-tenant secret.
1152
- */
1153
- interface SecretStore {
1154
- get(key: string): Promise<string | undefined>;
1155
- }
1156
- /** Object storage mediated by the host (presigned broker under the hood). */
1157
- interface StorageBroker {
1158
- getUrl(key: string): Promise<string>;
1159
- put(key: string, body: Uint8Array | string): Promise<void>;
1160
- }
1161
- /**
1162
- * Monotonic sequence numbers owned and PERSISTED by the host. A stateless
1163
- * plugin cannot keep its own counter (it holds no per-tenant state and the same
1164
- * object serves every tenant), yet some gateways require a strictly increasing,
1165
- * unique-per-merchant number (e.g. Serfinsa's `audit_no`). The plugin asks the
1166
- * host for the next value under a plugin-chosen `scope` string; the host does
1167
- * the atomic increment and durable storage.
1168
- *
1169
- * `scope` namespaces the counter — encode everything that must have its own run
1170
- * of numbers, e.g. `serfinsa:audit_no:<merchantId>`. Two calls with the same
1171
- * scope never return the same value; different scopes are independent.
1172
- */
1173
- interface SequenceStore {
1174
- next(scope: string): Promise<number>;
1175
- }
1176
- type DomainEventName = string;
1177
- type DomainEventHandler = (payload: unknown) => void | Promise<void>;
1178
- /**
1179
- * The one object a plugin factory receives. It is the plugin's ENTIRE window
1180
- * into the host — no `@nestjs/*`, no prisma, no `process`. Everything the
1181
- * plugin can do flows through these ports, which lets the host enforce the
1182
- * plugin's declared permissions and swap the transport (in-process today,
1183
- * worker/WASM later) without touching plugin code.
1184
- */
1185
- interface HostApi {
1186
- readonly logger: Logger;
1187
- readonly http: HttpClient;
1188
- readonly secrets: SecretStore;
1189
- readonly storage: StorageBroker;
1190
- readonly sequence: SequenceStore;
1191
- /** Subscribe to a host domain event (order.created, product.updated, ...). */
1192
- on(event: DomainEventName, handler: DomainEventHandler): void;
1193
- /** Expose a capability to the host's generic registry. */
1194
- registerCapability<T = unknown>(cap: Capability<T>): void;
1195
- }
1196
-
1197
39
  /** Wire format: `domain.action` or `domain.action:resource`. */
1198
40
  interface Permission {
1199
41
  domain: string;
@@ -1232,7 +74,7 @@ declare function checkPermissions(required: string[], grantedRaw: string[]): Per
1232
74
  * - MINOR: additive (new optional fields, new tokens) — backwards compatible.
1233
75
  * - PATCH: docs/fixes with zero shape changes.
1234
76
  */
1235
- declare const SDK_VERSION = "0.6.3";
77
+ declare const SDK_VERSION = "0.6.6";
1236
78
  /**
1237
79
  * True when a plugin built against `pluginSdkVersion` can run on a host that
1238
80
  * ships `hostSdkVersion`. Rule: same major, host minor >= plugin minor.
@@ -1241,4 +83,4 @@ declare const SDK_VERSION = "0.6.3";
1241
83
  */
1242
84
  declare function isSdkCompatible(pluginSdkVersion: string, hostSdkVersion: string): boolean;
1243
85
 
1244
- export { ANALYTICS_PLUGIN_TOKEN, type AccordionBlock, type AccordionSection, type ActionBlock, ActionVariant, type AnalyticsActionSource, type AnalyticsConsent, type AnalyticsEvent, type AnalyticsEventName, AnalyticsFeature, type AnalyticsItem, type AnalyticsMoney, type AnalyticsPluginConfig, type AnalyticsStaticConfig, type AnalyticsUserData, type AnalyticsUtm, type BannerBlock, type Block, type BlockBase, BlockType, type CalloutBlock, type Capability, CapabilityKind, type CardBlock, type CodConfig, type CodFeeConfig, CodFeeType, type ConditionalBlock, type ConditionalEquals, type ConditionalWhen, ConfigScope, type ConfigurablePlugin, type CopyFieldBlock, type CreateShipmentParams, type DispatchContext, type DividerBlock, type DomainEventHandler, type DomainEventName, type EmbedInit, type FieldBlock, type FieldDefinition, type FieldDependsOn, type FieldMap, type FieldOption, FieldType, FieldVariant, GatewayEnvironment, type GatewayStaticConfig, type GroupBlock, type HostApi, type HttpClient, type HttpRequest, type HttpResponse, type IAnalyticsPlugin, type IPaymentPlugin, type IPlugin, type IShippingPlugin, type ISuppliersPlugin, type InlineRowBlock, type KeyValueBlock, type KeyValueRow, LayoutMode, type Logger, type MarkdownBlock, MessageVariant, PAYMENT_PLUGIN_TOKEN, type PaymentCard, type PaymentCustomer, type PaymentGatewayCode, type PaymentPayload, type PaymentPluginConfig, type PaymentRenderMode, type PaymentResult, type PaymentSessionPayload, type PaymentSessionResult, type PaymentVerifyPayload, type Permission, type PermissionCheck, type PlaceSupplierOrderInput, type Plugin, type PluginActionContext, type PluginActionResult, type PluginConfigField, type PluginConfigFieldDependency, type PluginConfigResult, type PluginConfigValidation, type PluginFactory, type PluginManifest, PluginType, type RepeaterBlock, RepeaterSource, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, type SecretStore, type SelectOption, type SequenceStore, type SetupAction, type SetupLayout, type SetupLayoutValidation, type SetupStep, type ShipmentAddress, type ShipmentParcel, type ShipmentResult, type ShippingDefaultConfig, ShippingFeature, type ShippingPluginConfig, type ShippingQuote, type ShippingQuoteParams, type ShippingStaticConfig, StepStatusFrom, type StepStatusFromAction, type StepStatusFromFields, type StepStatusSource, type StorageBroker, type SupplierCatalogQuery, type SupplierFulfillmentEvent, type SupplierListing, type SupplierListingAttribute, type SupplierListingPage, type SupplierListingVariant, type SupplierMoney, type SupplierOrderAddressLevel, type SupplierOrderCustomer, type SupplierOrderLine, type SupplierOrderResult, type SupplierOrderStatus, type SupplierShipTo, type SupplierStock, type SuppliersDefaultConfig, SuppliersFeature, type SuppliersPluginConfig, type SuppliersStaticConfig, type TabItem, type TabsBlock, type ToggleBlock, type TrackingEvent, TransactionStatus, type WebhookSignatureResult, analyticsCapability, capability, checkPermissions, createPluginConfig, crossValidateSetupLayout, definePlugin, field, isConfigurablePlugin, isPermissionGranted, isPluginFactory, isSdkCompatible, parsePermission, paymentCapability, shippingCapability, suppliersCapability, validateSetupLayout };
86
+ export { ANALYTICS_PLUGIN_TOKEN, ConfigScope, type FieldDefinition, type FieldDependsOn, type FieldMap, FieldType, INVOICING_PLUGIN_TOKEN, PAYMENT_PLUGIN_TOKEN, type Permission, type PermissionCheck, PluginConfigField, type PluginConfigResult, type PluginConfigValidation, SDK_VERSION, SHIPPING_PLUGIN_TOKEN, SUPPLIERS_PLUGIN_TOKEN, SelectOption, checkPermissions, createPluginConfig, field, isPermissionGranted, isSdkCompatible, parsePermission };