@voyantjs/plugin-netopia 0.1.0

package/LICENSE

@@ -0,0 +1,109 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 PixelMakers Studio SRL
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly
+display and redistribute the Software for any Permitted Purpose identified
+below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing
+Use means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe
+our patents, the license grant above includes a license under our patents.
+If you make a claim against any party that the Software infringes or
+contributes to the infringement of any patent, then your patent license to
+the Software ends immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives
+of the Software.
+
+If you redistribute any copies, modifications or derivatives of the
+Software, you must include a copy of or a link to these Terms and Conditions
+and not remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A
+PARTICULAR PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO
+THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin
+of the Software, you have no right under these Terms and Conditions to use
+our trademarks, trade names, service marks or product names.
+
+---
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software
+under the Apache License, Version 2.0 that is effective on the second
+anniversary of the date we make the Software available. On or after that
+date, you may use the Software under the Apache License, Version 2.0, in
+which case the following will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.

package/README.md

@@ -0,0 +1,56 @@
+# `@voyantjs/plugin-netopia`
+
+Netopia hosted-card payment support for Voyant finance.
+
+This package sits on top of `@voyantjs/finance` and its `payment_sessions` model. It does not replace finance state. It starts a hosted Netopia checkout, stores provider references on the session, and reconciles callback payloads back into Voyant payments, captures, authorizations, invoices, and booking payment schedules.
+
+## Environment
+
+The default finance extension resolves its runtime config from:
+
+- `NETOPIA_URL`
+- `NETOPIA_API_KEY`
+- `NETOPIA_POS_SIGNATURE`
+- `NETOPIA_NOTIFY_URL`
+- `NETOPIA_REDIRECT_URL`
+
+You can also override these programmatically via `createNetopiaFinanceExtension(options)`.
+
+## Routes
+
+Mounted as a finance extension, the package exposes:
+
+- `POST /providers/netopia/payment-sessions/:sessionId/start`
+- `POST /providers/netopia/bookings/:bookingId/payment-schedules/:scheduleId/collect`
+- `POST /providers/netopia/bookings/:bookingId/guarantees/:guaranteeId/collect`
+- `POST /providers/netopia/invoices/:invoiceId/collect`
+- `POST /providers/netopia/callback`
+- `GET /providers/netopia/config`
+
+Because this is a finance extension, these routes mount under the finance module path in the app.
+
+## Usage
+
+```ts
+import { createNetopiaFinanceExtension } from "@voyantjs/plugin-netopia"
+
+const netopiaFinanceExtension = createNetopiaFinanceExtension()
+```
+
+Then include the returned extension in `createApp({ extensions: [...] })`.
+
+## Flow
+
+1. Either create a finance `payment_session` yourself, or use one of the collect routes to create one from a booking schedule, guarantee, or invoice.
+2. Start the hosted Netopia checkout.
+3. Redirect the customer to the returned provider `paymentURL`.
+4. Optionally send a payment-link or invoice notification as part of the collect flow.
+5. Netopia calls the callback route.
+6. The plugin completes, fails, or updates the session in finance.
+
+## Notes
+
+- Successful Netopia statuses default to `3` and `5`.
+- In-flight statuses default to `1` and `15`.
+- The callback path is idempotent for already-completed sessions.
+- Amount/currency mismatch on a supposedly successful callback fails the session instead of silently accepting it.

package/dist/src/client.d.ts

@@ -0,0 +1,10 @@
+import type { NetopiaFetch, NetopiaRuntimeOptions, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, ResolvedNetopiaRuntimeOptions } from "./types.js";
+export interface NetopiaClientApi {
+    startCardPayment(request: NetopiaStartPaymentRequest): Promise<NetopiaStartPaymentResponse>;
+}
+export interface NetopiaClientOptions extends Pick<ResolvedNetopiaRuntimeOptions, "apiUrl" | "apiKey"> {
+    fetch?: NetopiaFetch;
+}
+export declare function resolveNetopiaRuntimeOptions(bindings: Record<string, unknown> | undefined, options?: NetopiaRuntimeOptions): ResolvedNetopiaRuntimeOptions;
+export declare function createNetopiaClient(options: NetopiaClientOptions): NetopiaClientApi;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,6BAA6B,EAC9B,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAA;CAC5F;AAED,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,6BAA6B,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACpG,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,CA0B/B;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CA+CnF"}

package/dist/src/client.js

@@ -0,0 +1,71 @@
+export function resolveNetopiaRuntimeOptions(bindings, options = {}) {
+    const env = bindings ?? {};
+    const apiUrl = options.apiUrl ?? coerceString(env.NETOPIA_URL);
+    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)
+        throw new Error("Missing Netopia config: NETOPIA_POS_SIGNATURE");
+    if (!notifyUrl)
+        throw new Error("Missing Netopia config: NETOPIA_NOTIFY_URL");
+    if (!redirectUrl)
+        throw new Error("Missing Netopia config: NETOPIA_REDIRECT_URL");
+    return {
+        apiUrl,
+        apiKey,
+        posSignature,
+        notifyUrl,
+        redirectUrl,
+        emailTemplate: options.emailTemplate ?? "confirm",
+        language: options.language ?? "ro",
+        successStatuses: options.successStatuses ?? [3, 5],
+        processingStatuses: options.processingStatuses ?? [1, 15],
+        fetch: options.fetch,
+    };
+}
+function coerceString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function createNetopiaClient(options) {
+    const apiUrl = options.apiUrl.replace(/\/$/, "");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    async function request(method, path, body) {
+        if (!fetchImpl) {
+            throw new Error("Netopia client requires a fetch implementation");
+        }
+        const response = await fetchImpl(`${apiUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: options.apiKey,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let text = "";
+        let json = null;
+        try {
+            text = await response.text();
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Surface raw text in the thrown error below.
+        }
+        return { ok: response.ok, status: response.status, json, text };
+    }
+    return {
+        async startCardPayment(requestBody) {
+            const res = await request("POST", "/payment/card/start", requestBody);
+            const json = (res.json ?? {});
+            if (!res.ok || json.error) {
+                throw new Error(`Netopia start payment failed (${json.error?.code ?? res.status}): ${json.error?.message ?? res.text}`);
+            }
+            return json;
+        },
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { createNetopiaClient, resolveNetopiaRuntimeOptions, type NetopiaClientApi, type NetopiaClientOptions, } from "./client.js";
+export { createNetopiaFinanceExtension, createNetopiaFinanceRoutes, netopiaFinanceExtension, netopiaHonoPlugin, } from "./plugin.js";
+export { deriveNetopiaOrderId, mapNetopiaPaymentStatus, netopiaService, type NetopiaCallbackResult, type NetopiaCollectPaymentResult, type NetopiaStartPaymentResult, } from "./service.js";
+export type { NetopiaBillingAddress, NetopiaBrowserData, NetopiaFetch, NetopiaInstallments, NetopiaPaymentInstrument, NetopiaPaymentOptions, NetopiaProductLine, NetopiaRuntimeOptions, NetopiaStartPaymentInput, NetopiaStartPaymentRequest, NetopiaStartPaymentResponse, NetopiaWebhookPayload, ResolvedNetopiaRuntimeOptions, } from "./types.js";
+export { netopiaBillingAddressSchema, netopiaCollectBookingGuaranteeSchema, netopiaCollectBookingScheduleSchema, netopiaCollectInvoiceSchema, netopiaBrowserDataSchema, netopiaInstallmentsSchema, netopiaPaymentInstrumentSchema, netopiaPaymentOptionsSchema, netopiaProductLineSchema, netopiaStartPaymentSessionSchema, netopiaWebhookPayloadSchema, } from "./validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,GAC/B,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,oCAAoC,EACpC,mCAAmC,EACnC,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { createNetopiaClient, resolveNetopiaRuntimeOptions, } from "./client.js";
+export { createNetopiaFinanceExtension, createNetopiaFinanceRoutes, netopiaFinanceExtension, netopiaHonoPlugin, } from "./plugin.js";
+export { deriveNetopiaOrderId, mapNetopiaPaymentStatus, netopiaService, } from "./service.js";
+export { netopiaBillingAddressSchema, netopiaCollectBookingGuaranteeSchema, netopiaCollectBookingScheduleSchema, netopiaCollectInvoiceSchema, netopiaBrowserDataSchema, netopiaInstallmentsSchema, netopiaPaymentInstrumentSchema, netopiaPaymentOptionsSchema, netopiaProductLineSchema, netopiaStartPaymentSessionSchema, netopiaWebhookPayloadSchema, } from "./validation.js";