@umohpyro/better-auth-nuvion 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +141 -3
- package/dist/client.cjs +33 -0
- package/dist/client.d.cts +12 -0
- package/dist/client.d.ts +12 -0
- package/dist/client.js +8 -0
- package/dist/engine.cjs +343 -0
- package/dist/engine.d.cts +151 -0
- package/dist/engine.d.ts +151 -0
- package/dist/engine.js +308 -0
- package/dist/index.cjs +741 -0
- package/dist/index.d.cts +470 -0
- package/dist/index.d.ts +470 -0
- package/dist/index.js +706 -0
- package/dist/types-BWF8YNYE.d.cts +108 -0
- package/dist/types-BWF8YNYE.d.ts +108 -0
- package/package.json +60 -6
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
type FeeBearer = "payer" | "merchant";
|
|
2
|
+
/** What an org's PARENT takes from money flowing through this org. */
|
|
3
|
+
interface FeeRule {
|
|
4
|
+
organizationId: string;
|
|
5
|
+
flatMinor: number;
|
|
6
|
+
bps: number;
|
|
7
|
+
minMinor?: number;
|
|
8
|
+
capMinor?: number;
|
|
9
|
+
bearer: FeeBearer;
|
|
10
|
+
}
|
|
11
|
+
interface ChainNode {
|
|
12
|
+
organizationId: string;
|
|
13
|
+
rule?: FeeRule;
|
|
14
|
+
}
|
|
15
|
+
interface Leg {
|
|
16
|
+
organizationId: string;
|
|
17
|
+
amountMinor: number;
|
|
18
|
+
}
|
|
19
|
+
interface Quote {
|
|
20
|
+
baseMinor: number;
|
|
21
|
+
chargedMinor: number;
|
|
22
|
+
legs: Leg[];
|
|
23
|
+
}
|
|
24
|
+
declare function validateRule(r: FeeRule): void;
|
|
25
|
+
/** fee = flat + floor(amount * bps / 10000), clamped to [min, cap], never more than the amount. BigInt avoids overflow. */
|
|
26
|
+
declare function computeFee(amountMinor: number, r?: FeeRule): number;
|
|
27
|
+
/**
|
|
28
|
+
* Cascade child -> parent. chain[0] is the leaf (the merchant the payer pays), last is the root (platform).
|
|
29
|
+
* Level i (non-root) keeps inflow_i - fee_i and passes fee_i up as inflow_{i+1}.
|
|
30
|
+
* Fees are floored, so every round-down stays with the parent and ultimately the platform, which receives
|
|
31
|
+
* the final inflow. Sum of legs === chargedMinor by construction (asserted).
|
|
32
|
+
*/
|
|
33
|
+
declare function quote(baseMinor: number, chain: ChainNode[]): Quote;
|
|
34
|
+
|
|
35
|
+
type PaymentStatus = "pending" | "received" | "splitting" | "settled" | "partial" | "refunded" | "refund_partial";
|
|
36
|
+
type LegState = "pending" | "sent" | "completed" | "failed" | "cancelled";
|
|
37
|
+
type LegKind = "split" | "reversal";
|
|
38
|
+
interface Payment {
|
|
39
|
+
id: string;
|
|
40
|
+
organizationId: string;
|
|
41
|
+
reference: string;
|
|
42
|
+
providerSessionId?: string;
|
|
43
|
+
baseMinor: number;
|
|
44
|
+
chargedMinor: number;
|
|
45
|
+
currency: string;
|
|
46
|
+
status: PaymentStatus;
|
|
47
|
+
createdAt: number;
|
|
48
|
+
}
|
|
49
|
+
interface PaymentLeg {
|
|
50
|
+
id: string;
|
|
51
|
+
paymentId: string;
|
|
52
|
+
kind: LegKind;
|
|
53
|
+
fromOrganizationId: string;
|
|
54
|
+
toOrganizationId: string;
|
|
55
|
+
amountMinor: number;
|
|
56
|
+
state: LegState;
|
|
57
|
+
attempt: number;
|
|
58
|
+
providerRef?: string;
|
|
59
|
+
error?: string | null;
|
|
60
|
+
}
|
|
61
|
+
/** Minimal persistence the engine needs. The Better Auth adapter and MemoryStore both implement it. */
|
|
62
|
+
interface Store {
|
|
63
|
+
getRule(orgId: string): Promise<FeeRule | undefined>;
|
|
64
|
+
parentOf(orgId: string): Promise<string | null | undefined>;
|
|
65
|
+
insertPayment(p: Payment): Promise<void>;
|
|
66
|
+
getPayment(id: string): Promise<Payment | undefined>;
|
|
67
|
+
findPaymentByReference(ref: string): Promise<Payment | undefined>;
|
|
68
|
+
/** compare-and-set; returns false if the current status is not in `from`. */
|
|
69
|
+
transitionPayment(id: string, from: PaymentStatus[], to: PaymentStatus): Promise<boolean>;
|
|
70
|
+
/** true the first time an event id is seen. */
|
|
71
|
+
claimEvent(eventId: string): Promise<boolean>;
|
|
72
|
+
insertLegs(legs: PaymentLeg[]): Promise<void>;
|
|
73
|
+
getLeg(id: string): Promise<PaymentLeg | undefined>;
|
|
74
|
+
legsOf(paymentId: string): Promise<PaymentLeg[]>;
|
|
75
|
+
updateLeg(id: string, patch: Partial<PaymentLeg>): Promise<void>;
|
|
76
|
+
}
|
|
77
|
+
type ProviderErrorKind = "rejected" | "duplicate" | "ambiguous";
|
|
78
|
+
declare class ProviderError extends Error {
|
|
79
|
+
kind: ProviderErrorKind;
|
|
80
|
+
constructor(kind: ProviderErrorKind, message: string);
|
|
81
|
+
}
|
|
82
|
+
interface TransferRequest {
|
|
83
|
+
fromOrganizationId: string;
|
|
84
|
+
toOrganizationId: string;
|
|
85
|
+
amountMinor: number;
|
|
86
|
+
currency: string;
|
|
87
|
+
reference: string;
|
|
88
|
+
narration: string;
|
|
89
|
+
}
|
|
90
|
+
/** Implemented per rail: Nuvion today, Paystack/Flutterwave later. */
|
|
91
|
+
interface PaymentProvider {
|
|
92
|
+
createCheckout(req: {
|
|
93
|
+
organizationId: string;
|
|
94
|
+
amountMinor: number;
|
|
95
|
+
currency: string;
|
|
96
|
+
reference: string;
|
|
97
|
+
narration: string;
|
|
98
|
+
redirectUrl: string;
|
|
99
|
+
}): Promise<{
|
|
100
|
+
sessionId: string;
|
|
101
|
+
checkoutUrl: string;
|
|
102
|
+
}>;
|
|
103
|
+
transfer(req: TransferRequest): Promise<{
|
|
104
|
+
providerRef: string;
|
|
105
|
+
}>;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export { type ChainNode as C, type FeeRule as F, type LegKind as L, type Payment as P, type Quote as Q, type Store as S, type TransferRequest as T, type PaymentLeg as a, type PaymentStatus as b, type LegState as c, type PaymentProvider as d, type FeeBearer as e, type Leg as f, ProviderError as g, type ProviderErrorKind as h, computeFee as i, quote as q, validateRule as v };
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
type FeeBearer = "payer" | "merchant";
|
|
2
|
+
/** What an org's PARENT takes from money flowing through this org. */
|
|
3
|
+
interface FeeRule {
|
|
4
|
+
organizationId: string;
|
|
5
|
+
flatMinor: number;
|
|
6
|
+
bps: number;
|
|
7
|
+
minMinor?: number;
|
|
8
|
+
capMinor?: number;
|
|
9
|
+
bearer: FeeBearer;
|
|
10
|
+
}
|
|
11
|
+
interface ChainNode {
|
|
12
|
+
organizationId: string;
|
|
13
|
+
rule?: FeeRule;
|
|
14
|
+
}
|
|
15
|
+
interface Leg {
|
|
16
|
+
organizationId: string;
|
|
17
|
+
amountMinor: number;
|
|
18
|
+
}
|
|
19
|
+
interface Quote {
|
|
20
|
+
baseMinor: number;
|
|
21
|
+
chargedMinor: number;
|
|
22
|
+
legs: Leg[];
|
|
23
|
+
}
|
|
24
|
+
declare function validateRule(r: FeeRule): void;
|
|
25
|
+
/** fee = flat + floor(amount * bps / 10000), clamped to [min, cap], never more than the amount. BigInt avoids overflow. */
|
|
26
|
+
declare function computeFee(amountMinor: number, r?: FeeRule): number;
|
|
27
|
+
/**
|
|
28
|
+
* Cascade child -> parent. chain[0] is the leaf (the merchant the payer pays), last is the root (platform).
|
|
29
|
+
* Level i (non-root) keeps inflow_i - fee_i and passes fee_i up as inflow_{i+1}.
|
|
30
|
+
* Fees are floored, so every round-down stays with the parent and ultimately the platform, which receives
|
|
31
|
+
* the final inflow. Sum of legs === chargedMinor by construction (asserted).
|
|
32
|
+
*/
|
|
33
|
+
declare function quote(baseMinor: number, chain: ChainNode[]): Quote;
|
|
34
|
+
|
|
35
|
+
type PaymentStatus = "pending" | "received" | "splitting" | "settled" | "partial" | "refunded" | "refund_partial";
|
|
36
|
+
type LegState = "pending" | "sent" | "completed" | "failed" | "cancelled";
|
|
37
|
+
type LegKind = "split" | "reversal";
|
|
38
|
+
interface Payment {
|
|
39
|
+
id: string;
|
|
40
|
+
organizationId: string;
|
|
41
|
+
reference: string;
|
|
42
|
+
providerSessionId?: string;
|
|
43
|
+
baseMinor: number;
|
|
44
|
+
chargedMinor: number;
|
|
45
|
+
currency: string;
|
|
46
|
+
status: PaymentStatus;
|
|
47
|
+
createdAt: number;
|
|
48
|
+
}
|
|
49
|
+
interface PaymentLeg {
|
|
50
|
+
id: string;
|
|
51
|
+
paymentId: string;
|
|
52
|
+
kind: LegKind;
|
|
53
|
+
fromOrganizationId: string;
|
|
54
|
+
toOrganizationId: string;
|
|
55
|
+
amountMinor: number;
|
|
56
|
+
state: LegState;
|
|
57
|
+
attempt: number;
|
|
58
|
+
providerRef?: string;
|
|
59
|
+
error?: string | null;
|
|
60
|
+
}
|
|
61
|
+
/** Minimal persistence the engine needs. The Better Auth adapter and MemoryStore both implement it. */
|
|
62
|
+
interface Store {
|
|
63
|
+
getRule(orgId: string): Promise<FeeRule | undefined>;
|
|
64
|
+
parentOf(orgId: string): Promise<string | null | undefined>;
|
|
65
|
+
insertPayment(p: Payment): Promise<void>;
|
|
66
|
+
getPayment(id: string): Promise<Payment | undefined>;
|
|
67
|
+
findPaymentByReference(ref: string): Promise<Payment | undefined>;
|
|
68
|
+
/** compare-and-set; returns false if the current status is not in `from`. */
|
|
69
|
+
transitionPayment(id: string, from: PaymentStatus[], to: PaymentStatus): Promise<boolean>;
|
|
70
|
+
/** true the first time an event id is seen. */
|
|
71
|
+
claimEvent(eventId: string): Promise<boolean>;
|
|
72
|
+
insertLegs(legs: PaymentLeg[]): Promise<void>;
|
|
73
|
+
getLeg(id: string): Promise<PaymentLeg | undefined>;
|
|
74
|
+
legsOf(paymentId: string): Promise<PaymentLeg[]>;
|
|
75
|
+
updateLeg(id: string, patch: Partial<PaymentLeg>): Promise<void>;
|
|
76
|
+
}
|
|
77
|
+
type ProviderErrorKind = "rejected" | "duplicate" | "ambiguous";
|
|
78
|
+
declare class ProviderError extends Error {
|
|
79
|
+
kind: ProviderErrorKind;
|
|
80
|
+
constructor(kind: ProviderErrorKind, message: string);
|
|
81
|
+
}
|
|
82
|
+
interface TransferRequest {
|
|
83
|
+
fromOrganizationId: string;
|
|
84
|
+
toOrganizationId: string;
|
|
85
|
+
amountMinor: number;
|
|
86
|
+
currency: string;
|
|
87
|
+
reference: string;
|
|
88
|
+
narration: string;
|
|
89
|
+
}
|
|
90
|
+
/** Implemented per rail: Nuvion today, Paystack/Flutterwave later. */
|
|
91
|
+
interface PaymentProvider {
|
|
92
|
+
createCheckout(req: {
|
|
93
|
+
organizationId: string;
|
|
94
|
+
amountMinor: number;
|
|
95
|
+
currency: string;
|
|
96
|
+
reference: string;
|
|
97
|
+
narration: string;
|
|
98
|
+
redirectUrl: string;
|
|
99
|
+
}): Promise<{
|
|
100
|
+
sessionId: string;
|
|
101
|
+
checkoutUrl: string;
|
|
102
|
+
}>;
|
|
103
|
+
transfer(req: TransferRequest): Promise<{
|
|
104
|
+
providerRef: string;
|
|
105
|
+
}>;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export { type ChainNode as C, type FeeRule as F, type LegKind as L, type Payment as P, type Quote as Q, type Store as S, type TransferRequest as T, type PaymentLeg as a, type PaymentStatus as b, type LegState as c, type PaymentProvider as d, type FeeBearer as e, type Leg as f, ProviderError as g, type ProviderErrorKind as h, computeFee as i, quote as q, validateRule as v };
|
package/package.json
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@umohpyro/better-auth-nuvion",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@umohpyro/better-auth-nuvion",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Better Auth plugin for Nuvion: hosted checkout, multi-level fee splits and child merchants. Unofficial pre-release.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"sideEffects": false,
|
|
8
|
+
"keywords": [
|
|
9
|
+
"better-auth",
|
|
10
|
+
"better-auth-plugin",
|
|
11
|
+
"nuvion",
|
|
12
|
+
"payments",
|
|
13
|
+
"split-payments",
|
|
14
|
+
"marketplace"
|
|
15
|
+
],
|
|
16
|
+
"homepage": "https://better-auth-nuvion-docs.vercel.app",
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/umohpyro/better-auth-nuvion.git"
|
|
20
|
+
},
|
|
21
|
+
"engines": {
|
|
22
|
+
"node": ">=20"
|
|
23
|
+
},
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
|
|
27
|
+
"require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
|
|
28
|
+
},
|
|
29
|
+
"./client": {
|
|
30
|
+
"import": { "types": "./dist/client.d.ts", "default": "./dist/client.js" },
|
|
31
|
+
"require": { "types": "./dist/client.d.cts", "default": "./dist/client.cjs" }
|
|
32
|
+
},
|
|
33
|
+
"./engine": {
|
|
34
|
+
"import": { "types": "./dist/engine.d.ts", "default": "./dist/engine.js" },
|
|
35
|
+
"require": { "types": "./dist/engine.d.cts", "default": "./dist/engine.cjs" }
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"main": "./dist/index.cjs",
|
|
39
|
+
"module": "./dist/index.js",
|
|
40
|
+
"types": "./dist/index.d.ts",
|
|
41
|
+
"files": [
|
|
42
|
+
"dist",
|
|
43
|
+
"README.md",
|
|
44
|
+
"LICENSE"
|
|
45
|
+
],
|
|
46
|
+
"peerDependencies": {
|
|
47
|
+
"better-auth": ">=1.7.0"
|
|
48
|
+
},
|
|
49
|
+
"dependencies": {
|
|
50
|
+
"zod": "^4.0.0"
|
|
51
|
+
},
|
|
52
|
+
"scripts": {
|
|
53
|
+
"build": "tsup",
|
|
54
|
+
"clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
55
|
+
"prepack": "node scripts/copy-readme.mjs"
|
|
56
|
+
},
|
|
57
|
+
"publishConfig": {
|
|
58
|
+
"access": "public"
|
|
59
|
+
}
|
|
60
|
+
}
|