@voyantjs/plugin-netopia 0.18.0 → 0.20.0

package/dist/client.d.ts

@@ -1,4 +1,16 @@
-import type { NetopiaFetch, NetopiaRuntimeOptions, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, ResolvedNetopiaRuntimeOptions } from "./types.js";
+import type { NetopiaFetch, NetopiaMode, NetopiaRuntimeOptions, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, ResolvedNetopiaRuntimeOptions } from "./types.js";
+/**
+ * Known Netopia API base URLs. The client appends `/payment/card/start`
+ * (and any future paths) to whichever value is selected via `mode`. To
+ * point at a staging proxy or test mock — or if your tenant is provisioned
+ * on a non-default host — set `NETOPIA_URL` (or pass `apiUrl`) to override.
+ *
+ * The two hosts use *different* path conventions:
+ *   - live host has a `/pay` prefix on every endpoint
+ *   - sandbox host serves endpoints from the root
+ * Sourced from the protravel-v3 reference implementation.
+ */
+export declare const NETOPIA_API_BASES: Record<NetopiaMode, string>;
 export interface NetopiaClientApi {
     startCardPayment(request: NetopiaStartPaymentRequest): Promise<NetopiaStartPaymentResponse>;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,6BAA6B,EAC9B,MAAM,YAAY,CAAA;AAGnB,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAA;CAC5F;AAED,MAAM,WAAW,oBACf,SAAQ,IAAI,CAAC,6BAA6B,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChE,KAAK,CAAC,EAAE,YAAY,CAAA;CACrB;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,OAAO,GAAE,qBAA0B,GAClC,6BAA6B,CAuC/B;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CA+CnF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,6BAA6B,EAC9B,MAAM,YAAY,CAAA;AAGnB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAGzD,CAAA;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAA;CAC5F;AAED,MAAM,WAAW,oBACf,SAAQ,IAAI,CAAC,6BAA6B,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChE,KAAK,CAAC,EAAE,YAAY,CAAA;CACrB;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,OAAO,GAAE,qBAA0B,GAClC,6BAA6B,CAwC/B;AAgBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CA2DnF"}

package/dist/client.js

@@ -1,14 +1,29 @@
 import { ZodError } from "zod";
 import { resolvedNetopiaRuntimeOptionsSchema } from "./validation.js";
+/**
+ * Known Netopia API base URLs. The client appends `/payment/card/start`
+ * (and any future paths) to whichever value is selected via `mode`. To
+ * point at a staging proxy or test mock — or if your tenant is provisioned
+ * on a non-default host — set `NETOPIA_URL` (or pass `apiUrl`) to override.
+ *
+ * The two hosts use *different* path conventions:
+ *   - live host has a `/pay` prefix on every endpoint
+ *   - sandbox host serves endpoints from the root
+ * Sourced from the protravel-v3 reference implementation.
+ */
+export const NETOPIA_API_BASES = {
+    live: "https://secure.mobilpay.ro/pay",
+    sandbox: "https://secure.sandbox.netopia-payments.com",
+};
 export function resolveNetopiaRuntimeOptions(bindings, options = {}) {
     const env = bindings ?? {};
-    const apiUrl = options.apiUrl ?? coerceString(env.NETOPIA_URL);
+    const apiUrlOverride = options.apiUrl ?? coerceString(env.NETOPIA_URL);
+    const mode = resolveMode(options.mode ?? coerceString(env.NETOPIA_MODE));
+    const apiUrl = apiUrlOverride ?? NETOPIA_API_BASES[mode];
     const apiKey = options.apiKey ?? coerceString(env.NETOPIA_API_KEY);
     const posSignature = options.posSignature ?? coerceString(env.NETOPIA_POS_SIGNATURE);
     const notifyUrl = options.notifyUrl ?? coerceString(env.NETOPIA_NOTIFY_URL);
     const redirectUrl = options.redirectUrl ?? coerceString(env.NETOPIA_REDIRECT_URL);
-    if (!apiUrl)
-        throw new Error("Missing Netopia config: NETOPIA_URL");
     if (!apiKey)
         throw new Error("Missing Netopia config: NETOPIA_API_KEY");
     if (!posSignature)
@@ -47,6 +62,16 @@ export function resolveNetopiaRuntimeOptions(bindings, options = {}) {
 function coerceString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function resolveMode(raw) {
+    if (raw === "live" || raw === "sandbox")
+        return raw;
+    if (raw !== undefined) {
+        throw new Error(`Invalid NETOPIA_MODE: ${raw} (expected "sandbox" or "live")`);
+    }
+    // Default to sandbox so a half-configured production deploy fails into
+    // the safer environment instead of charging real cards.
+    return "sandbox";
+}
 export function createNetopiaClient(options) {
     const apiUrl = options.apiUrl.replace(/\/$/, "");
     const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -78,10 +103,27 @@ export function createNetopiaClient(options) {
         async startCardPayment(requestBody) {
             const res = await request("POST", "/payment/card/start", requestBody);
             const json = (res.json ?? {});
+            // Netopia quirk (per protravel-v3 reference): error code 101 means
+            // "redirect customer to payment page" — it's success-with-redirect,
+            // not a failure. The API sometimes omits `paymentURL` in this case;
+            // upstream callers fall back to other fields on the session.
+            if (json.error && String(json.error.code) === "101") {
+                return json;
+            }
             if (!res.ok || json.error) {
-                throw new Error(`Netopia start payment failed (${json.error?.code ?? res.status}): ${json.error?.message ?? res.text}`);
+                const detail = json.error?.message ??
+                    (res.status === 404
+                        ? `Endpoint not found at ${apiUrl}/payment/card/start. Verify NETOPIA_MODE/NETOPIA_URL.`
+                        : stripHtml(res.text).slice(0, 200));
+                throw new Error(`Netopia start payment failed (${json.error?.code ?? res.status}): ${detail}`);
             }
             return json;
         },
     };
 }
+function stripHtml(text) {
+    return text
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { createNetopiaCheckoutStarter } from "./checkout.js";
-export { createNetopiaClient, type NetopiaClientApi, type NetopiaClientOptions, resolveNetopiaRuntimeOptions, } from "./client.js";
+export { createNetopiaClient, NETOPIA_API_BASES, type NetopiaClientApi, type NetopiaClientOptions, resolveNetopiaRuntimeOptions, } from "./client.js";
 export type { NetopiaNotificationRuntime, NetopiaNotificationRuntimeOptions, } from "./notification-runtime.js";
 export { buildNetopiaNotificationRuntime } from "./notification-runtime.js";
-export { createNetopiaFinanceExtension, createNetopiaFinanceExtension as createNetopiaFinanceAdapter, createNetopiaFinanceRoutes, NETOPIA_RUNTIME_CONTAINER_KEY, netopiaFinanceExtension, netopiaHonoPlugin as createNetopiaAdapterBundle, netopiaHonoPlugin, } from "./plugin.js";
+export { createNetopiaFinanceExtension, createNetopiaFinanceExtension as createNetopiaFinanceAdapter, createNetopiaFinanceRoutes, NETOPIA_RUNTIME_CONTAINER_KEY, netopiaFinanceExtension, netopiaHonoBundle, netopiaHonoPlugin as createNetopiaAdapterBundle, netopiaHonoPlugin, } from "./plugin.js";
 export { deriveNetopiaOrderId, mapNetopiaPaymentStatus, type NetopiaCallbackResult, type NetopiaCollectPaymentResult, type NetopiaStartPaymentResult, netopiaService, } from "./service.js";
-export type { NetopiaBillingAddress, NetopiaBrowserData, NetopiaFetch, NetopiaInstallments, NetopiaPaymentInstrument, NetopiaPaymentOptions, NetopiaProductLine, NetopiaRuntimeOptions, NetopiaStartPaymentInput, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, NetopiaWebhookPayload, ResolvedNetopiaRuntimeOptions, } from "./types.js";
+export type { NetopiaBillingAddress, NetopiaBrowserData, NetopiaFetch, NetopiaInstallments, NetopiaMode, NetopiaPaymentInstrument, NetopiaPaymentOptions, NetopiaProductLine, NetopiaRuntimeOptions, NetopiaStartPaymentInput, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, NetopiaWebhookPayload, ResolvedNetopiaRuntimeOptions, } from "./types.js";
 export { netopiaBillingAddressSchema, netopiaBrowserDataSchema, netopiaCollectBookingGuaranteeSchema, netopiaCollectBookingScheduleSchema, netopiaCollectInvoiceSchema, netopiaInstallmentsSchema, netopiaPaymentInstrumentSchema, netopiaPaymentOptionsSchema, netopiaProductLineSchema, netopiaRuntimeOptionsSchema, netopiaStartPaymentSessionSchema, netopiaWebhookPayloadSchema, resolvedNetopiaRuntimeOptionsSchema, } from "./validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,4BAA4B,GAC7B,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAA;AAC3E,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,IAAI,2BAA2B,EAC5D,0BAA0B,EAC1B,6BAA6B,EAC7B,uBAAuB,EACvB,iBAAiB,IAAI,0BAA0B,EAC/C,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,oCAAoC,EACpC,mCAAmC,EACnC,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,gCAAgC,EAChC,2BAA2B,EAC3B,mCAAmC,GACpC,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,4BAA4B,GAC7B,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAA;AAC3E,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,IAAI,2BAA2B,EAC5D,0BAA0B,EAC1B,6BAA6B,EAC7B,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,IAAI,0BAA0B,EAC/C,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,oCAAoC,EACpC,mCAAmC,EACnC,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,gCAAgC,EAChC,2BAA2B,EAC3B,mCAAmC,GACpC,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export { createNetopiaCheckoutStarter } from "./checkout.js";
-export { createNetopiaClient, resolveNetopiaRuntimeOptions, } from "./client.js";
+export { createNetopiaClient, NETOPIA_API_BASES, resolveNetopiaRuntimeOptions, } from "./client.js";
 export { buildNetopiaNotificationRuntime } from "./notification-runtime.js";
-export { createNetopiaFinanceExtension, createNetopiaFinanceExtension as createNetopiaFinanceAdapter, createNetopiaFinanceRoutes, NETOPIA_RUNTIME_CONTAINER_KEY, netopiaFinanceExtension, netopiaHonoPlugin as createNetopiaAdapterBundle, netopiaHonoPlugin, } from "./plugin.js";
+export { createNetopiaFinanceExtension, createNetopiaFinanceExtension as createNetopiaFinanceAdapter, createNetopiaFinanceRoutes, NETOPIA_RUNTIME_CONTAINER_KEY, netopiaFinanceExtension, netopiaHonoBundle, netopiaHonoPlugin as createNetopiaAdapterBundle, netopiaHonoPlugin, } from "./plugin.js";
 export { deriveNetopiaOrderId, mapNetopiaPaymentStatus, netopiaService, } from "./service.js";
 export { netopiaBillingAddressSchema, netopiaBrowserDataSchema, netopiaCollectBookingGuaranteeSchema, netopiaCollectBookingScheduleSchema, netopiaCollectInvoiceSchema, netopiaInstallmentsSchema, netopiaPaymentInstrumentSchema, netopiaPaymentOptionsSchema, netopiaProductLineSchema, netopiaRuntimeOptionsSchema, netopiaStartPaymentSessionSchema, netopiaWebhookPayloadSchema, resolvedNetopiaRuntimeOptionsSchema, } from "./validation.js";

package/dist/plugin.d.ts

@@ -41,7 +41,7 @@ export declare function createNetopiaFinanceRoutes(options?: NetopiaRuntimeOptio
                         completedAt: string | null;
                         paymentId: string | null;
                         amountCents: number;
-                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
                         targetId: string | null;
                         orderId: string | null;
                         invoiceId: string | null;
@@ -233,7 +233,7 @@ export declare function createNetopiaFinanceRoutes(options?: NetopiaRuntimeOptio
                         completedAt: string | null;
                         paymentId: string | null;
                         amountCents: number;
-                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
                         targetId: string | null;
                         orderId: string | null;
                         invoiceId: string | null;
@@ -394,7 +394,7 @@ export declare function createNetopiaFinanceRoutes(options?: NetopiaRuntimeOptio
                         completedAt: string | null;
                         paymentId: string | null;
                         amountCents: number;
-                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
                         targetId: string | null;
                         orderId: string | null;
                         invoiceId: string | null;
@@ -553,7 +553,7 @@ export declare function createNetopiaFinanceRoutes(options?: NetopiaRuntimeOptio
                         completedAt: string | null;
                         paymentId: string | null;
                         amountCents: number;
-                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
                         targetId: string | null;
                         orderId: string | null;
                         invoiceId: string | null;
@@ -642,7 +642,7 @@ export declare function createNetopiaFinanceRoutes(options?: NetopiaRuntimeOptio
                         completedAt: string | null;
                         paymentId: string | null;
                         amountCents: number;
-                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee";
+                        targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
                         targetId: string | null;
                         orderId: string | null;
                         invoiceId: string | null;

package/dist/service-callback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-callback.d.ts","sourceRoot":"","sources":["../src/service-callback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAGjE,OAAO,EAKL,KAAK,qBAAqB,EAE3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAE9E,wBAAsB,cAAc,CAClC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,qBAAqB,EAC9B,cAAc,GAAE,qBAA0B,EAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,cAAc,GAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC3C,OAAO,CAAC,qBAAqB,CAAC,CAmJhC"}
+{"version":3,"file":"service-callback.d.ts","sourceRoot":"","sources":["../src/service-callback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAGjE,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAE9E,wBAAsB,cAAc,CAClC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,qBAAqB,EAC9B,cAAc,GAAE,qBAA0B,EAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,cAAc,GAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC3C,OAAO,CAAC,qBAAqB,CAAC,CAqIhC"}

package/dist/service-callback.js

@@ -1,5 +1,5 @@
 import { resolveNetopiaRuntimeOptions } from "./client.js";
-import { amountToCents, financeService, mapNetopiaPaymentStatus, mergeRecord, normalizeCurrency, } from "./service-shared.js";
+import { financeService, mapNetopiaPaymentStatus, mergeRecord, } from "./service-shared.js";
 export async function handleCallback(db, payload, runtimeOptions = {}, bindings, financeRuntime = {}) {
     const runtime = resolveNetopiaRuntimeOptions(bindings, runtimeOptions);
     const orderId = payload.order.orderID;
@@ -25,26 +25,15 @@ export async function handleCallback(db, payload, runtimeOptions = {}, bindings,
     const providerPayload = mergeRecord(session.providerPayload, {
         netopiaCallback: payload,
     });
-    const normalizedCurrency = normalizeCurrency(payload.payment.currency);
-    const amountCents = amountToCents(payload.payment.amount);
-    if (callbackState === "completed" &&
-        (normalizedCurrency !== normalizeCurrency(session.currency) ||
-            amountCents !== session.amountCents)) {
-        const failed = await financeService.failPaymentSession(db, session.id, {
-            providerSessionId: payload.payment.ntpID,
-            providerPaymentId: payload.payment.ntpID,
-            externalReference: orderId,
-            failureCode: "amount_or_currency_mismatch",
-            failureMessage: `Expected ${session.amountCents} ${normalizeCurrency(session.currency)}, received ${amountCents} ${normalizedCurrency}`,
-            providerPayload,
-        });
-        return {
-            action: "failed",
-            reason: "amount_or_currency_mismatch",
-            session: failed,
-            orderId,
-        };
-    }
+    // Note: we intentionally don't validate `payment.amount` / `payment.currency`
+    // against the session. Netopia auto-converts non-RON orders into RON for
+    // processing (so an EUR session always callbacks with `currency: "RON"` and
+    // a converted amount). Any strict equality check here would reject every
+    // legitimate cross-currency payment. The trustworthy field is
+    // `payment.status` — the orderID is the unguessable secret that ties the
+    // callback to the session, and Netopia is the only party that knows it.
+    // For tamper detection beyond that, wrap this handler at the route layer
+    // and verify the processed amount via your own FX source.
     if (callbackState === "processing") {
         const updated = await financeService.updatePaymentSession(db, session.id, {
             status: "processing",

package/dist/types.d.ts

@@ -132,7 +132,16 @@ export interface NetopiaStartPaymentInput {
     metadata?: Record<string, unknown>;
     notes?: string | null;
 }
+export type NetopiaMode = "sandbox" | "live";
 export interface NetopiaRuntimeOptions {
+    /**
+     * Selects the Netopia environment. Resolves to a known base URL via
+     * `NETOPIA_API_BASES`. Pass `apiUrl` to override (e.g. for tests or a
+     * private staging proxy). Defaults to `"sandbox"` when neither `mode`
+     * nor `apiUrl` is set, so a misconfigured production deploy fails into
+     * the safer mode rather than charging real cards.
+     */
+    mode?: NetopiaMode;
     apiUrl?: string;
     apiKey?: string;
     posSignature?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-netopia",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -39,11 +39,11 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/checkout": "0.18.0",
-    "@voyantjs/core": "0.18.0",
-    "@voyantjs/finance": "0.18.0",
-    "@voyantjs/hono": "0.18.0",
-    "@voyantjs/notifications": "0.18.0"
+    "@voyantjs/checkout": "0.20.0",
+    "@voyantjs/core": "0.20.0",
+    "@voyantjs/finance": "0.20.0",
+    "@voyantjs/hono": "0.20.0",
+    "@voyantjs/notifications": "0.20.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",