@spring-payments/payments-react-native 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spring Payments
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# Spring Payments for React Native / Expo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A React Native library: a ready-made **Add debit or credit card** button opens native card entry. Partners do not initialize Stripe, handle intents, or build card fields. Card policy, customer authorization, saved accounts, removals, charging and duplicate-card decisions remain on Spring/partner backends.
+
+Target: Expo SDK 57, RN 0.86, Stripe React Native 0.64.x. Type checks and mocked contract tests are not certification of native 3DS behavior. Use a development build, not Expo Go, as the release verification environment. iOS/Android device tests remain a release gate. This package does not support React Native Web; use `@spring-payments/payments-js` on web.
+
+Expo SDK 57 requires Node.js 22.13+ and Xcode 26.4+ for local iOS builds ([Expo requirements](https://docs.expo.dev/versions/latest/)). Older Swift compilers reject Expo's `weak let` declarations; upgrade the toolchain rather than patching Expo's Swift sources.
+
+With Xcode 27/iOS 27, SDK 57 apps must also opt into Expo's scene lifecycle: install
+`expo-build-properties` with `npx expo install expo-build-properties` and add
+`["expo-build-properties", { "ios": { "enableSceneSupport": true } }]` to your Expo
+plugins. This is app-level Expo setup, not a Spring theme option.
+
+## Install
+
+For Expo SDK 57 / React Native 0.86:
+
+```sh
+npx expo install @spring-payments/payments-react-native @stripe/stripe-react-native@0.64.0
+```
+
+The published npm package is the only supported partner distribution. Partners do not need access to Spring's private repository and should not copy source or install supplied tarballs. Use the compatible Stripe version above rather than assuming an arbitrary latest version is supported. Browser apps must likewise install `@spring-payments/payments-js` from npm; direct Gateway module imports and no-build integrations are not supported.
+
+Configure your dedicated return scheme, then create/rebuild your development app:
+
+```json
+{
+  "expo": {
+    "plugins": [["@spring-payments/payments-react-native", { "scheme": "partnerpayments" }]]
+  }
+}
+```
+
+The plugin preserves existing schemes and adds this one. Native Stripe code is autolinked; wallets are deliberately not enabled. No Apple merchant ID is needed for card-only entry. Run `npx expo run:ios`, `npx expo run:android`, or your existing EAS development-build workflow. Installing JS or an OTA update alone cannot add the native dependency.
+
+For bare React Native, install the package and compatible Stripe dependency normally, run your iOS CocoaPods installation, and register the dedicated URL scheme with your app's iOS/Android configuration. No Expo runtime dependency is required by this SDK. Do not add another StripeProvider or initialize Stripe separately while a Spring flow is active.
+
+## One provider and one button
+
+```tsx
+import { SpringPaymentsProvider, SpringAddCardButton } from '@spring-payments/payments-react-native';
+
+const options = {
+  applicationId: 'com.partner.app',
+  returnUrl: 'partnerpayments://safepay',
+  gatewayOrigin: 'https://dev.gateway.pay-api.springpayments.com',
+  merchantDisplayName: 'Your Business',
+  createSession: request => authenticatedPartnerApi.createPaymentSession(request),
+};
+
+export function App() {
+  return (
+    <SpringPaymentsProvider options={options}>
+      <SpringAddCardButton onResult={result => {
+        if (result.status === 'COMPLETED') refreshSavedCards();
+        if (result.status === 'PENDING') reconcileWithPartnerBackend(result);
+      }} />
+    </SpringPaymentsProvider>
+  );
+}
+```
+
+Mount one provider above navigation. Exact web/native layouts differ; entry point, purpose and completion semantics are consistent.
+
+## Styling: no Spring theme by default
+
+`SpringAddCardButton` adds no colors, fonts, padding, rounding, opacity, or layout styles. React Native's default `Text`, `View` and `Pressable` rendering still applies. Stripe's native sheet also retains its own defaults unless you supply `appearance`. The green button in the example is explicitly styled by that app.
+
+| Prop | What you control |
+| --- | --- |
+| `style` | The launch `Pressable`; accepts a style, array, or `({pressed}) => style` callback |
+| `textStyle` | Launch button text: font, size, weight, color and alignment |
+| `containerStyle` | The wrapping `View`: layout, width, spacing and background |
+| `statusStyle` | Status/error text styling |
+| `label`, `busyLabel`, `busyMessage` | Launch label and in-progress copy |
+| `messages` | Override `COMPLETED`, `PENDING`, `CANCELLED`, `FAILED` result messages |
+| `disabled` | Disable the launch button; busy operations also disable it automatically |
+
+```tsx
+const payments = useSpringPayments(); // Inside the provider.
+<SpringAddCardButton
+  label="Add a card"
+  style={({ pressed }) => ({
+    backgroundColor: '#234db5', padding: 14, minHeight: 48,
+    borderRadius: 6, opacity: pressed || payments.busy ? 0.6 : 1,
+  })}
+  textStyle={{ color: '#fff', fontSize: 16, textAlign: 'center' }}
+  containerStyle={{ marginVertical: 16 }}
+  statusStyle={{ color: '#333', marginTop: 8 }}
+  messages={{ FAILED: 'We could not save your card. Please try again.' }}
+/>
+```
+
+Your styles should provide sufficient touch targets, readable contrast and appropriate disabled/pressed states. `useSpringPayments().busy` lets your theme reflect pending operations. Accessibility roles, disabled/busy semantics and live status text remain in the component. Use your own button with `addCard()` for arbitrary icons, children or layout; you then own its accessibility and status presentation.
+
+**Style the card sheet separately** using the provider's `options.appearance` (`PaymentSheet.AppearanceParams`). Stripe supports colors (including light/dark), fonts, shapes/borders and primary-button appearance, with platform-specific limits. `options.saveCardLabel` customizes Save; `merchantDisplayName` identifies your business. Neither option styles the launch button. For example:
+
+```ts
+const themedOptions = {
+  ...options, // The session options above; pass themedOptions to the provider.
+  appearance: {
+    colors: { primary: '#234db5' },
+    shapes: { borderRadius: 6 },
+  },
+  saveCardLabel: 'Save card',
+};
+```
+
+We pass these settings to Stripe without imposing a Spring theme. They do not allow arbitrary native-sheet layout, field order or replacement card inputs. Bank-owned 3DS challenge content is not freely themeable. Web Appearance API rules and native PaymentSheet appearance are different schemas, not an interchangeable cross-platform theme object.
+
+For your own button, call `useSpringPayments().addCard()`. To recover an existing off-session payment call `useSpringPayments().authenticatePayment(paymentId)`. Both return safe results, and the hook exposes `busy` and `result`. Do not create a new charge or save a replacement card for authentication recovery.
+
+## Backend session adapter
+
+`createSession` receives `{purpose,applicationId,returnUrl,paymentId?}` and returns `{sessionId,sessionToken,expiresAt,componentUrl}`. Your authenticated backend resolves the customer and authorizes the operation, then uses Spring's M2M API:
+
+- Add card: `POST /api/external/spg/v1/clients/{key}/native-card-sessions`
+- Authenticate: `POST /api/external/spg/v1/clients/{key}/payments/{paymentId}/native-authentication-sessions`
+- Both take `{applicationId,returnUrl}` and `Idempotency-Key`.
+
+Spring must register the partner UUID, application ID and exact return URL before native sessions can be issued. The app never holds Spring M2M credentials. `gatewayOrigin` restricts where the SDK sends the capability. The application-ID header identifies the session audience, not proof of app authenticity.
+
+Keep an operation's idempotency key on the partner side and reuse it after network uncertainty or returning to the app; do not silently mint a fresh setup on each retry. A replay first checks Spring status, so a completed setup does not present another sheet. For an expired add-card session, reconcile the saved-account list before authorizing a new operation. Payment recovery additionally has the existing payment-status API.
+
+## Results and lifecycle
+
+- **COMPLETED**: Spring confirmed the saved account or original payment. Add-card includes `paymentAccountId`; authentication includes `paymentId`. A native sheet's success alone is not completion.
+- **PENDING**: The operation is unresolved, with a safe `sessionId` and, for payment authentication, `paymentId`. Bounded polling stops after 10 reads; check/replay the same operation through your backend rather than starting a duplicate.
+- **FAILED**: Safe `UNAVAILABLE`, `EXPIRED`, or `REJECTED` code; no raw Stripe or transport errors.
+- **CANCELLED** is reserved for cancellation known to occur before submission. The current native sheet does not expose whether the user tapped Save before dismissing, so dismissal conservatively reconciles and returns COMPLETED or PENDING, **not a claim that no card was saved**. Web can distinguish closing before its explicit submission button.
+
+Only one native operation may present at a time. Duplicate calls for the same operation share the underlying work; a competing operation gets UNAVAILABLE. Do not change the provider's customer/session context or sign in as another customer while a sheet is open.
+
+The dedicated return URL must be `<your-scheme>://safepay` in this SDK version: direct iOS confirmation uses Stripe's fixed suffix. The provider forwards matching iOS Linking callbacks internally. Android retains Stripe's native return handling; no JS Linking event is required for success. Configure partner navigation/analytics to ignore this dedicated callback route and never log its query parameters. Do not store capabilities, processor client secrets or callback URLs in persistent storage.
+
+After process death there is no retained JS promise/session. Restore partner login, reconcile/replay the operation through `createSession`, and let Spring determine completion; URL arrival is not payment success. Partners remain responsible for consent to future off-session charges and prompting absent customers to return.
+
+## Spring-hosted payment recovery (preferred)
+
+For a customer returning to finish an existing payment, Spring's hosted browser recovery page remains the preferred option. This is a Spring-owned application, not a hosted SDK distribution. Embedded native card entry and in-app authentication still use this npm package.
+
+Send the customer to your authenticated web handoff page. Its backend authorizes the original payment and creates a **web** authentication session using the Gateway origin and `{gatewayOrigin}/payment-components/recover` as the return URL. The handoff submits `sessionId` and `sessionToken` in a browser form POST body to that page. Never put capabilities in a deep link, query string or fragment, and never send a native session to the web recovery page. A browser redirect or return to the app is not proof of payment; reconcile the original payment through your backend. Partners choosing in-app recovery instead can use `authenticatePayment(paymentId)` as described above.
+
+## Verification
+
+`npm test` compiles against the actual RN/Stripe types and tests backend-confirmed completion, bounded pending, unknown submission/dismissal, scope mismatch, safe errors, replay/concurrent operations and plugin behavior. `npm pack` verifies the distributable includes compiled JS/types and the Expo plugin. Before release, verify fresh Expo installation and native builds on both platforms, actual card-only PaymentSheet (no saved cards/Link/wallets), issuer 3DS success/cancellation, app switching/process death, accessibility/text scaling and real Gateway webhook timing.
+
+The 0.1.x releases are initial integration releases, not certification of a live payment flow. iOS simulator Release build and styled/unstyled UI checks have passed; actual PaymentSheet/3DS with a configured backend and Android native verification remain outstanding. Complete those checks before a production integration.
+
+## License
+
+MIT; see [LICENSE](./LICENSE). This license covers the Spring code in this SDK package, not Spring's backend, other repository directories, trademarks or access to payment services. Third-party dependencies retain their own licenses; Stripe services remain subject to their own terms. Preserve required notices in redistributed apps. The source repository may remain private; recipients may reuse and redistribute this package under MIT.
+
+## Maintaining and publishing (Spring maintainers)
+
+Source of truth: `packages/spring-payments-react-native/` in the private `ktechgit/spring-payments` repository. Edit `src/`, `app.plugin.js` and this README here. `dist/` is generated; do not edit it. The repository's `examples/embedded-partner-expo/` is the integration consumer, not the package source. Local tarballs below are for maintainer release validation only, not an alternative partner installation route.
+
+From this directory:
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+npm pack
+```
+
+The `prepack` script compiles TypeScript. Inspect the actual tarball: only compiled `dist/*.js` and `dist/*.d.ts`, `app.plugin.js`, `README.md`, `LICENSE` and `package.json` belong in it. Do not ship source maps, tests, app configuration, credentials or stale build files. Install the tarball in a clean Expo consumer, check plugin resolution and types, and verify native builds and the supported payment flows before promoting a release for production use.
+
+For subsequent releases, choose a semantic version and run `npm version patch --no-git-tag-version` (or `minor` / `major`) before packing; keep the lockfile synchronized. Never overwrite or reuse a published version. Review and commit source/version changes through Spring's release workflow.
+
+Authenticate interactively with `npm login --registry=https://registry.npmjs.org/`; confirm the account with `npm whoami` and its publish access to `@spring-payments`. Keep npm credentials in the maintainer/build environment only. With release authorization, publish the exact inspected tarball (replace the version in its filename):
+
+```sh
+npm publish ./spring-payments-payments-react-native-0.1.1.tgz --access public --registry=https://registry.npmjs.org/
+npm view @spring-payments/payments-react-native@0.1.1 version license dist.integrity --registry=https://registry.npmjs.org/
+```
+
+For a preview release, use a prerelease version and `--tag next`; do not move `latest` inadvertently. After registry verification, install the published version in the Expo demo, regenerate its lockfile, run its typecheck and Expo configuration check, and update partner installation instructions. An npm release does not deploy Gateway configuration, authorize a native application or complete device/processor certification.

package/app.plugin.js

@@ -0,0 +1,9 @@
+// Expo already translates `scheme` into both platforms' native URL registrations.
+module.exports = function withSpringPayments(config, { scheme } = {}) {
+  if (typeof scheme !== 'string' || !/^[a-z][a-z0-9+.-]+$/.test(scheme)
+      || ['http', 'https', 'file', 'data', 'javascript', 'intent', 'exp', 'exps'].includes(scheme)) {
+    throw new Error('Spring Payments requires a dedicated application URL scheme');
+  }
+  const schemes = config.scheme ? [].concat(config.scheme) : [];
+  return { ...config, scheme: [...new Set([...schemes, scheme])] };
+};

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import { type PressableProps, type StyleProp, type TextStyle, type ViewStyle } from 'react-native';
+import { type PaymentSheet } from '@stripe/stripe-react-native';
+import { type Options, type Result } from './session';
+export type { Session, SessionRequest, Result } from './session';
+export interface SpringPaymentsOptions extends Options {
+    appearance?: PaymentSheet.AppearanceParams;
+    saveCardLabel?: string;
+}
+type Payments = {
+    addCard(): Promise<Result>;
+    authenticatePayment(paymentId: string): Promise<Result>;
+    busy: boolean;
+    result?: Result;
+};
+/** Mount once above partner navigation so authentication returns keep their owner alive. */
+export declare function SpringPaymentsProvider({ options, children }: React.PropsWithChildren<{
+    options: SpringPaymentsOptions;
+}>): React.JSX.Element;
+export declare function useSpringPayments(): Payments;
+export declare function SpringAddCardButton({ label, busyLabel, busyMessage, disabled, style, textStyle, statusStyle, containerStyle, messages: customMessages, onResult }: {
+    label?: string;
+    busyLabel?: string;
+    busyMessage?: string;
+    disabled?: boolean;
+    style?: PressableProps['style'];
+    textStyle?: StyleProp<TextStyle>;
+    statusStyle?: StyleProp<TextStyle>;
+    containerStyle?: StyleProp<ViewStyle>;
+    messages?: Partial<Record<Result['status'], string>>;
+    onResult?: (result: Result) => void;
+}): React.JSX.Element;

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpringPaymentsProvider = SpringPaymentsProvider;
+exports.useSpringPayments = useSpringPayments;
+exports.SpringAddCardButton = SpringAddCardButton;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const react_native_url_polyfill_1 = require("react-native-url-polyfill");
+const stripe_react_native_1 = require("@stripe/stripe-react-native");
+const session_1 = require("./session");
+const Context = (0, react_1.createContext)(null);
+/** Mount once above partner navigation so authentication returns keep their owner alive. */
+function SpringPaymentsProvider({ options, children }) {
+    const current = (0, react_1.useRef)(options);
+    current.current = options;
+    const [busy, setBusy] = (0, react_1.useState)(false);
+    const [result, setResult] = (0, react_1.useState)();
+    const mounted = (0, react_1.useRef)(true);
+    (0, react_1.useEffect)(() => {
+        mounted.current = true;
+        // Forward only this provider's return route; never log URLs carrying processor parameters.
+        const handle = (url) => {
+            if (!url)
+                return;
+            try {
+                const incoming = new react_native_url_polyfill_1.URL(url), expected = new react_native_url_polyfill_1.URL(current.current.returnUrl);
+                if (incoming.protocol === expected.protocol && incoming.host === expected.host
+                    && incoming.pathname === expected.pathname)
+                    void (0, stripe_react_native_1.handleURLCallback)(url).catch(() => { });
+            }
+            catch { /* Not a payment return URL. */ }
+        };
+        void react_native_1.Linking.getInitialURL().then(handle).catch(() => { });
+        const subscription = react_native_1.Linking.addEventListener('url', event => handle(event.url));
+        return () => { mounted.current = false; subscription.remove(); };
+    }, []);
+    const payments = (0, react_1.useMemo)(() => {
+        const config = { ...options, createSession: (request) => current.current.createSession(request) };
+        async function initialize(state) {
+            await (0, stripe_react_native_1.initStripe)({ publishableKey: state.publishableKey, urlScheme: new react_native_url_polyfill_1.URL(config.returnUrl).protocol.slice(0, -1) });
+        }
+        return (0, session_1.createPayments)(config, {
+            async addCard(state) {
+                await initialize(state);
+                const initialized = await (0, stripe_react_native_1.initPaymentSheet)({
+                    merchantDisplayName: config.merchantDisplayName,
+                    setupIntentClientSecret: state.clientSecret,
+                    customFlow: false,
+                    returnURL: config.returnUrl,
+                    primaryButtonLabel: current.current.saveCardLabel || 'Save card',
+                    appearance: current.current.appearance,
+                    link: { display: stripe_react_native_1.LinkDisplay.NEVER },
+                    // No CustomerSession/ephemeral credentials, wallets, or saved-card manager.
+                });
+                if (initialized.error)
+                    throw new Error('UNAVAILABLE');
+                const presented = await (0, stripe_react_native_1.presentPaymentSheet)();
+                if (presented.error)
+                    throw new Error('UNCONFIRMED');
+            },
+            async authenticatePayment(state) {
+                await initialize(state);
+                const retrieved = await (0, stripe_react_native_1.retrievePaymentIntent)(state.clientSecret);
+                if (retrieved.error || !retrieved.paymentIntent)
+                    throw new Error('UNAVAILABLE');
+                const intent = retrieved.paymentIntent;
+                if (intent.status === 'RequiresAction') {
+                    const response = await (0, stripe_react_native_1.handleNextAction)(state.clientSecret, config.returnUrl);
+                    if (response.error)
+                        throw new Error('UNCONFIRMED');
+                }
+                else if (intent.status === 'RequiresPaymentMethod' || intent.status === 'RequiresConfirmation') {
+                    const paymentMethodId = intent.paymentMethod?.id || intent.lastPaymentError?.paymentMethod?.id || intent.paymentMethodId;
+                    if (!paymentMethodId)
+                        throw new Error('UNAVAILABLE');
+                    const response = await (0, stripe_react_native_1.confirmPayment)(state.clientSecret, {
+                        paymentMethodType: 'Card', paymentMethodData: { paymentMethodId },
+                    });
+                    if (response.error)
+                        throw new Error('UNCONFIRMED');
+                }
+                else if (!['Succeeded', 'Processing'].includes(intent.status))
+                    throw new Error('UNAVAILABLE');
+            },
+        }, undefined, undefined, react_native_url_polyfill_1.URL);
+    }, [options.applicationId, options.returnUrl, options.gatewayOrigin, options.merchantDisplayName]);
+    const pendingCalls = (0, react_1.useRef)(0);
+    const run = (0, react_1.useCallback)(async (operation) => {
+        pendingCalls.current++;
+        setBusy(true);
+        setResult(undefined);
+        try {
+            const value = await operation();
+            if (mounted.current)
+                setResult(value);
+            return value;
+        }
+        finally {
+            pendingCalls.current--;
+            if (mounted.current)
+                setBusy(pendingCalls.current > 0);
+        }
+    }, []);
+    return (0, jsx_runtime_1.jsx)(Context.Provider, { value: { busy, result,
+            addCard: () => run(payments.addCard), authenticatePayment: id => run(() => payments.authenticatePayment(id)) }, children: children });
+}
+function useSpringPayments() {
+    const payments = (0, react_1.useContext)(Context);
+    if (!payments)
+        throw new Error('Mount SpringPaymentsProvider above payment controls');
+    return payments;
+}
+function SpringAddCardButton({ label = 'Add debit or credit card', busyLabel = 'Saving card…', busyMessage = 'Complete verification, then wait for Spring confirmation.', disabled = false, style, textStyle, statusStyle, containerStyle, messages: customMessages, onResult }) {
+    const payments = useSpringPayments();
+    const [result, setResult] = (0, react_1.useState)();
+    const messages = { COMPLETED: 'Card saved.', PENDING: 'Card setup is not yet confirmed. Check your saved cards before trying again.',
+        CANCELLED: 'Card entry cancelled.', FAILED: 'Unable to save the card. Please try again.', ...customMessages };
+    return (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: containerStyle, children: [(0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessibilityRole: "button", accessibilityState: { disabled: disabled || payments.busy, busy: payments.busy }, disabled: disabled || payments.busy, style: style, onPress: () => { setResult(undefined); void payments.addCard().then(value => { setResult(value); onResult?.(value); }); }, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: textStyle, children: payments.busy ? busyLabel : label }) }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { accessibilityLiveRegion: "polite", style: statusStyle, children: payments.busy ? busyMessage : result ? messages[result.status] : '' })] });
+}

package/dist/session.d.ts

@@ -0,0 +1,51 @@
+export type Purpose = 'ADD_CARD' | 'AUTHENTICATE_PAYMENT';
+export interface Session {
+    sessionId: string;
+    sessionToken: string;
+    expiresAt: string;
+    componentUrl: string;
+}
+export interface SessionRequest {
+    purpose: Purpose;
+    applicationId: string;
+    returnUrl: string;
+    paymentId?: string;
+}
+export interface State {
+    purpose: Purpose;
+    status: string;
+    publishableKey?: string;
+    clientSecret?: string;
+    returnUrl: string;
+    paymentAccountId?: string;
+    paymentId?: string;
+}
+export type Result = {
+    status: 'COMPLETED';
+    paymentAccountId?: string;
+    paymentId?: string;
+} | {
+    status: 'PENDING';
+    sessionId?: string;
+    paymentId?: string;
+} | {
+    status: 'CANCELLED';
+} | {
+    status: 'FAILED';
+    code: 'UNAVAILABLE' | 'EXPIRED' | 'REJECTED';
+};
+export interface Options {
+    applicationId: string;
+    returnUrl: string;
+    gatewayOrigin: string;
+    merchantDisplayName: string;
+    createSession: (request: SessionRequest) => Promise<Session>;
+}
+export interface Processor {
+    addCard(state: State): Promise<void>;
+    authenticatePayment(state: State): Promise<void>;
+}
+export declare function createPayments(options: Options, processor: Processor, transport?: typeof fetch, delay?: (ms: number) => Promise<unknown>, URLParser?: new (value: string) => Pick<URL, 'protocol' | 'origin' | 'username' | 'password' | 'search' | 'hash' | 'hostname' | 'host' | 'pathname' | 'href'>): {
+    addCard: () => Promise<Result>;
+    authenticatePayment: (paymentId: string) => Promise<Result>;
+};

package/dist/session.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPayments = createPayments;
+// PaymentSheet and Stripe initialization are process-wide. Never overlap presentations,
+// even when partners accidentally mount multiple providers.
+let presenting = false;
+function createPayments(options, processor, transport = fetch, delay = (ms) => new Promise(resolve => setTimeout(resolve, ms)), URLParser = URL) {
+    const gateway = new URLParser(options.gatewayOrigin);
+    const returnUrl = new URLParser(options.returnUrl);
+    if (gateway.protocol !== 'https:' || gateway.origin !== options.gatewayOrigin
+        || gateway.username || gateway.password || gateway.search || gateway.hash
+        || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(options.applicationId)
+        || !returnUrl.hostname || returnUrl.username || returnUrl.password || returnUrl.search || returnUrl.hash
+        || returnUrl.host !== 'safepay' || returnUrl.pathname !== ''
+        || ['http:', 'https:', 'file:', 'data:', 'javascript:', 'intent:', 'exp:', 'exps:'].includes(returnUrl.protocol)
+        || !options.merchantDisplayName.trim())
+        throw new Error('Invalid Spring Payments configuration');
+    let active;
+    let activeOperation;
+    function run(purpose, paymentId) {
+        const operation = `${purpose}:${paymentId || ''}`;
+        if (active) {
+            return activeOperation === operation ? active : Promise.resolve({ status: 'FAILED', code: 'UNAVAILABLE' });
+        }
+        if (presenting)
+            return Promise.resolve({ status: 'FAILED', code: 'UNAVAILABLE' });
+        presenting = true;
+        activeOperation = operation;
+        active = execute(purpose, paymentId).finally(() => {
+            active = undefined;
+            activeOperation = undefined;
+            presenting = false;
+        });
+        return active;
+    }
+    async function execute(purpose, paymentId) {
+        let session;
+        let potentiallySubmitted = false;
+        const pending = () => ({ status: 'PENDING', ...(session ? { sessionId: session.sessionId } : {}),
+            ...(paymentId ? { paymentId } : {}) });
+        try {
+            if (purpose === 'AUTHENTICATE_PAYMENT' && !paymentId)
+                return { status: 'FAILED', code: 'UNAVAILABLE' };
+            session = await options.createSession({ purpose, applicationId: options.applicationId,
+                returnUrl: options.returnUrl, ...(paymentId ? { paymentId } : {}) });
+            const endpoint = new URLParser(session.componentUrl);
+            if (endpoint.origin !== gateway.origin || endpoint.username || endpoint.password || endpoint.search || endpoint.hash
+                || !/^[a-f0-9-]{36}$/.test(session.sessionId)
+                || endpoint.pathname !== `/api/public/payment-components/native-sessions/${session.sessionId}`
+                || !session.sessionToken || !Number.isFinite(Date.parse(session.expiresAt))) {
+                return { status: 'FAILED', code: 'UNAVAILABLE' };
+            }
+            async function read() {
+                if (Date.parse(session.expiresAt) <= Date.now())
+                    throw new Error('EXPIRED');
+                const abort = new AbortController();
+                const timeout = setTimeout(() => abort.abort(), 15000);
+                try {
+                    const response = await transport(endpoint.href, { method: 'GET',
+                        headers: { Authorization: `Bearer ${session.sessionToken}`, 'X-Spring-Application-Id': options.applicationId },
+                        credentials: 'omit', cache: 'no-store', redirect: 'error', signal: abort.signal });
+                    if (!response.ok)
+                        throw new Error(response.status === 410 ? 'EXPIRED' : 'UNAVAILABLE');
+                    const state = await response.json();
+                    if (state.purpose !== purpose || state.returnUrl !== options.returnUrl
+                        || (paymentId && state.paymentId !== paymentId))
+                        throw new Error('UNAVAILABLE');
+                    return state;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            function result(state) {
+                if (state.status === 'COMPLETED' || purpose === 'AUTHENTICATE_PAYMENT' && state.status === 'SUCCEEDED') {
+                    if (purpose === 'ADD_CARD' && !state.paymentAccountId)
+                        return pending();
+                    return { status: 'COMPLETED', ...(state.paymentAccountId ? { paymentAccountId: state.paymentAccountId } : {}),
+                        ...(paymentId ? { paymentId } : {}) };
+                }
+                if (['REJECTED', 'PAYMENT_FAILED', 'FAILED'].includes(state.status))
+                    return { status: 'FAILED', code: 'REJECTED' };
+            }
+            let state = await read();
+            const existing = result(state);
+            if (existing)
+                return existing;
+            if (['READY', 'AUTHENTICATION_REQUIRED'].includes(state.status)) {
+                if (!state.publishableKey || !state.clientSecret)
+                    throw new Error('UNAVAILABLE');
+                // A dismissed native sheet can follow a submission or 3DS attempt. Reconcile,
+                // never infer that closing the sheet undid an operation.
+                potentiallySubmitted = true;
+                try {
+                    if (purpose === 'ADD_CARD')
+                        await processor.addCard(state);
+                    else
+                        await processor.authenticatePayment(state);
+                }
+                catch {
+                    state = await read();
+                    return result(state) || pending();
+                }
+            }
+            else
+                potentiallySubmitted = true;
+            for (let attempt = 0; attempt < 10; attempt++) {
+                state = await read();
+                const finished = result(state);
+                if (finished)
+                    return finished;
+                if (state.status === 'AUTHENTICATION_REQUIRED')
+                    return pending();
+                if (attempt < 9)
+                    await delay(1500);
+            }
+            return pending();
+        }
+        catch (error) {
+            if (potentiallySubmitted)
+                return pending();
+            return { status: 'FAILED', code: error instanceof Error && error.message === 'EXPIRED' ? 'EXPIRED' : 'UNAVAILABLE' };
+        }
+    }
+    return { addCard: () => run('ADD_CARD'), authenticatePayment: (paymentId) => run('AUTHENTICATE_PAYMENT', paymentId) };
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@spring-payments/payments-react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "description": "Spring-managed native card saving and payment authentication",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktechgit/spring-payments.git",
+    "directory": "packages/spring-payments-react-native"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "react-native": "dist/index.js",
+  "files": [
+    "dist",
+    "app.plugin.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.cjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@stripe/stripe-react-native": "0.64.x",
+    "react": ">=19.2.0 <20",
+    "react-native": "0.86.x"
+  },
+  "devDependencies": {
+    "@stripe/stripe-react-native": "0.64.0",
+    "@types/react": "^19.2.0",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "react-native-url-polyfill": "^4.0.0"
+  }
+}