@soltech/fluid-common 1.16.0 → 1.18.0-sc24475.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/README.md CHANGED
@@ -3,18 +3,49 @@
3
3
 
4
4
  ## Contribution
5
5
 
6
- 1. Make a change
7
- 2. Bump the package version according to change severity
8
- 3. Commit
9
- 4. run `npm run pub` - it'll build the package, publish it to npm and push changes to github
10
-
11
- But during the time of development, another version could have been deployed, without your change only available in your Pull Request.
12
- And you need to keep your branch updated with the `main` one.
13
- In that case, follow these steps:
14
-
15
- 1. make sure your commons is up to date with main
16
- 2. create a branch out of main and make your changes or update the branch of the PR
17
- 3. bump the package version according to severity - that’s a bit tricky as that version may already be taken by a parallel work, so it’s worth checking other active branches or the npm itself
18
- 4. commit and push the branch
19
- 5. run `npm run pub` to publish the package
20
- 6. refer to the package in your branch in another repo
6
+ 1. Branch out of an up-to-date `main` (branch name: the Shortcut story number).
7
+ 2. Make your change in `src/`.
8
+ 3. Bump `version` in `package.json` (see [Versions](#versions)), then run `npm i` to update `package-lock.json`.
9
+ 4. Commit `src/`, `package.json` and `package-lock.json`.
10
+ 5. Push: `git push --set-upstream origin HEAD`.
11
+ 6. Publish (see [Publishing](#publishing)).
12
+ 7. In each consumer, install the exact version: `npm install @soltech/fluid-common@<version> --save-exact`.
13
+
14
+ Push before you publish, so npm never holds a package whose commit is missing from GitHub.
15
+ Do not use `npm run pub`: it publishes first and pushes after, and it cannot pass the tag a prerelease needs.
16
+
17
+ ### Versions
18
+
19
+ While a story is in progress, publish a **prerelease** named after it:
20
+
21
+ ```
22
+ <next version>-sc<story>.<n> e.g. 1.17.0-sc24475.0
23
+ ```
24
+
25
+ - `<next version>` must be higher than anything already on npm, including versions from parallel branches
26
+ that are not on `main` yet. Check with `npm view @soltech/fluid-common versions`.
27
+ A prerelease counts as older than the release it is named after, so `1.16.0-sc24475.0` comes before `1.16.0`.
28
+ - `<n>` starts at `0` and goes up each time you publish a change for the same story.
29
+ A published version can never be republished.
30
+ - Once the PR is approved and merged, publish the plain version (`1.17.0`) from `main`
31
+ and point the consumers at it.
32
+
33
+ Consumers pin an exact version (`"1.17.0-sc24475.0"`), never a caret range.
34
+
35
+ ### Publishing
36
+
37
+ A prerelease needs a dist-tag, otherwise npm refuses it
38
+ (`You must specify a tag using --tag when publishing a prerelease version`).
39
+ Use the story number as the tag, so `npm install @soltech/fluid-common` keeps resolving to the latest release:
40
+
41
+ ```
42
+ npm publish --tag sc24475
43
+ ```
44
+
45
+ A release from `main` takes no tag and becomes `latest`:
46
+
47
+ ```
48
+ npm publish
49
+ ```
50
+
51
+ `prepublishOnly` rebuilds `lib/` before every publish, so there is no separate build step.
package/lib/flows.d.ts ADDED
@@ -0,0 +1,93 @@
1
+ export declare const FLOW_SCHEMA_VERSION = 1;
2
+ export declare const FLOW_TRANSACTIONS: readonly ["deposit", "withdrawal", "quickDeposit", "inlineQuickDeposit", "*"];
3
+ export type FlowTransaction = typeof FLOW_TRANSACTIONS[number];
4
+ export declare const FLOW_ELEMENTS: readonly ["widget", "virtual", "inline"];
5
+ export type FlowElement = typeof FLOW_ELEMENTS[number];
6
+ export declare const HEADER_TITLE_KINDS: readonly ["CONTENT_KEY", "METHOD_NAME", "TRANSACTION_STATUS"];
7
+ export type HeaderTitleKind = typeof HEADER_TITLE_KINDS[number];
8
+ export interface ViewChrome {
9
+ header: {
10
+ titleType: HeaderTitleKind;
11
+ titleKey?: string;
12
+ subtitleKey?: string;
13
+ transactionToggleReplacesTitle?: boolean;
14
+ };
15
+ footer?: {
16
+ sticky: boolean;
17
+ ctaForNewMethod?: string;
18
+ ctaForStoredMethod?: string;
19
+ ctaForNewMethodAmongStored?: string;
20
+ ctaForFailure?: string;
21
+ };
22
+ hasForm?: boolean;
23
+ noBack?: boolean;
24
+ abortNeedsConfirmation?: boolean;
25
+ abortShowsAbandonModal?: boolean;
26
+ showRefreshWarning?: boolean;
27
+ }
28
+ export interface ViewChromeOverride extends Omit<Partial<ViewChrome>, 'header' | 'footer'> {
29
+ header?: Partial<ViewChrome['header']>;
30
+ footer?: Partial<NonNullable<ViewChrome['footer']>>;
31
+ }
32
+ export interface StepGuards {
33
+ conditions: {
34
+ condition: string;
35
+ handler: string;
36
+ }[];
37
+ alternativeCta: string;
38
+ }
39
+ export interface StepEntry {
40
+ id: string;
41
+ view: string;
42
+ features?: string[];
43
+ validity?: string;
44
+ autoEnter?: string;
45
+ advance?: string;
46
+ guards?: StepGuards;
47
+ chrome?: ViewChromeOverride;
48
+ }
49
+ export interface FlowDefinition {
50
+ id?: string;
51
+ slug: string;
52
+ entry: {
53
+ transaction: FlowTransaction;
54
+ element: FlowElement;
55
+ };
56
+ when?: string[];
57
+ setup?: string;
58
+ steps: StepEntry[];
59
+ }
60
+ export interface FlowSet {
61
+ schemaVersion: typeof FLOW_SCHEMA_VERSION;
62
+ catalogueVersion: string;
63
+ flows: FlowDefinition[];
64
+ }
65
+ export interface StepCatalogueEntry {
66
+ requires: string[];
67
+ terminal: boolean;
68
+ views: string[];
69
+ }
70
+ export interface ViewCatalogueEntry {
71
+ chrome: ViewChrome;
72
+ provides: string[];
73
+ features?: {
74
+ accepts: string[];
75
+ required: string[];
76
+ defaultOrder: string[];
77
+ };
78
+ }
79
+ export interface Catalogue {
80
+ catalogueVersion: string;
81
+ steps: Record<string, StepCatalogueEntry>;
82
+ views: Record<string, ViewCatalogueEntry>;
83
+ features: Record<string, {
84
+ provides: string[];
85
+ }>;
86
+ predicates: Record<string, {
87
+ needs: string[];
88
+ }>;
89
+ handlers: Record<string, {
90
+ provides: string[];
91
+ }>;
92
+ selectionFacts: string[];
93
+ }
package/lib/flows.js ADDED
@@ -0,0 +1,5 @@
1
+ export const FLOW_SCHEMA_VERSION = 1;
2
+ export const FLOW_TRANSACTIONS = ['deposit', 'withdrawal', 'quickDeposit', 'inlineQuickDeposit', '*'];
3
+ export const FLOW_ELEMENTS = ['widget', 'virtual', 'inline'];
4
+ // A string, not the widget's numeric enum: the canonical form a flow id is hashed from holds no numbers.
5
+ export const HEADER_TITLE_KINDS = ['CONTENT_KEY', 'METHOD_NAME', 'TRANSACTION_STATUS'];
package/lib/index.d.ts CHANGED
@@ -5,3 +5,4 @@ export * from './transactions.js';
5
5
  export * from './user.js';
6
6
  export * from './bonus.js';
7
7
  export * from './tracking.js';
8
+ export * from './flows.js';
package/lib/index.js CHANGED
@@ -5,3 +5,4 @@ export * from './transactions.js';
5
5
  export * from './user.js';
6
6
  export * from './bonus.js';
7
7
  export * from './tracking.js';
8
+ export * from './flows.js';
@@ -48,6 +48,12 @@ export interface PaymentMethod {
48
48
  encryptionSettings?: EncryptionSettings;
49
49
  hostedFields?: HostedFieldsSettings;
50
50
  deviceProtection?: DeviceProtectionSettings;
51
+ highlight?: PaymentMethodHighlight;
52
+ }
53
+ export type PaymentMethodHighlightTone = 'positive' | 'warning';
54
+ export interface PaymentMethodHighlight {
55
+ text: string;
56
+ tone: PaymentMethodHighlightTone;
51
57
  }
52
58
  /** Its presence is also how the client decides the gateway behind this method profiles at all. */
53
59
  export interface DeviceProtectionSettings {
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@soltech/fluid-common",
3
- "version": "1.16.0",
3
+ "version": "1.18.0-sc24475.0",
4
4
  "type": "module",
5
5
  "description": "Fluid frontend, API and AI common interfaces & enums",
6
6
  "main": "lib/index.js",
7
- "types:": "lib/index.d.ts",
7
+ "types": "lib/index.d.ts",
8
+ "files": [
9
+ "lib"
10
+ ],
8
11
  "scripts": {
9
12
  "dev": "tsc --watch",
10
13
  "build": "tsc",
package/.editorconfig DELETED
@@ -1,21 +0,0 @@
1
- # EditorConfig is awesome: https://EditorConfig.org
2
-
3
- # top-most EditorConfig file
4
- root = true
5
-
6
- # Unix-style newlines with a newline ending every file
7
- [*]
8
- charset = utf-8
9
- indent_style = tab
10
- indent_size = 4
11
- end_of_line = lf
12
- max_line_length = 140
13
- insert_final_newline = true
14
- trim_trailing_whitespace = true
15
-
16
- [*.md]
17
- trim_trailing_whitespace = false
18
- max_line_length = off
19
-
20
- [{package.json,package-lock.json}]
21
- max_line_length = off
package/.eslintignore DELETED
@@ -1,2 +0,0 @@
1
- lib
2
- node_modules
package/.eslintrc DELETED
@@ -1,11 +0,0 @@
1
- {
2
- "root": true,
3
- "extends": [
4
- "@soltech"
5
- ],
6
- "parserOptions": {
7
- "project": "./tsconfig.json",
8
- "ecmaVersion": 2020,
9
- "sourceType": "module"
10
- }
11
- }
package/.gitattributes DELETED
@@ -1,2 +0,0 @@
1
- # Auto detect text files and perform LF normalization
2
- * text=auto
@@ -1,13 +0,0 @@
1
- {
2
- "context": {
3
- "repos": [
4
- "soltechno/fluid-api",
5
- "soltechno/fluid-widget",
6
- "soltechno/fluid-payments",
7
- "soltechno/fluid-public-types",
8
- "soltechno/fluid-eslint-config",
9
- "soltechno/fluid-handbook",
10
- "soltechno/fluid-docs"
11
- ]
12
- }
13
- }
package/.husky/pre-commit DELETED
@@ -1,3 +0,0 @@
1
- #!/usr/bin/env sh
2
-
3
- npx lint-staged
package/.nvmrc DELETED
@@ -1,2 +0,0 @@
1
- v22.12.0
2
-
package/AGENTS.md DELETED
@@ -1,5 +0,0 @@
1
- # AGENTS.md
2
-
3
- ## Primary instruction
4
-
5
- This repository's canonical agent instructions live in `CLAUDE.md`.
package/CLAUDE.md DELETED
@@ -1,78 +0,0 @@
1
- # CLAUDE.md – Instructions for AI Coding Agents
2
-
3
- Read this entire file before every task.
4
-
5
- ## Agent Rules & Safety
6
- - Never edit any files when the current git branch is `main` — always work on a feature branch. Run `git branch --show-current` to confirm before making any changes.
7
- - Never touch `.env*`, `certs/` or any file containing secrets/credentials.
8
- - Never introduce new dependencies without asking first.
9
- - Never rewrite large parts of the codebase unless explicitly requested.
10
- - Never put Shortcut ticket numbers (`sc-XXXXX` or bare story IDs) in code or test files — use descriptive names/comments instead. Ticket links belong only in PR descriptions and branch names, never in source. Some older tests embed IDs in `describe` blocks; do not copy that pattern.
11
- - Keep comments to only what is necessary — comment the *why* behind non-obvious decisions, not the *what* of self-explanatory code. Don't narrate obvious operations, restate the code in prose, or leave placeholder/TODO noise. Prefer clear names over explanatory comments.
12
- - Always propose changes as diffs or small file edits and get approval before applying.
13
- - If unsure about architecture, style, or impact, ask before coding.
14
-
15
- ## Project Overview & Architecture
16
- - TypeScript-only package containing shared interfaces and enums used by both `fluid-widget` (frontend) and `fluid-api` (API/middleware).
17
- - Source of truth is the domain modules in `src/` (`wallet`, `wallet-config-keys`, `payment-methods`, `transactions`, `user`, `bonus`, `tracking`). `src/index.ts` only re-exports them — add a new type to the module it belongs to, never to `index.ts`.
18
- - Build output is generated in `lib/` and must not be edited by hand.
19
-
20
- ## Build, Dev & Validation
21
- - Build: `npm run build`
22
- - Lint: `npm run lint`
23
- - Publish: see Publishing Flow below
24
-
25
- ### Developing against a consumer
26
-
27
- `fluid-api` and `fluid-widget` import the built `lib/`, never `src/`. To test a change without publishing:
28
-
29
- ```bash
30
- npm run build && npm link # here
31
- cd ../fluid-api && npm link @soltech/fluid-common # and in each consumer
32
- ```
33
-
34
- Two things fail silently, with no error in either repo:
35
-
36
- - **`lib/` goes stale.** Consumers read `lib/`, so an edit to `src/` is invisible until it is rebuilt. Keep `npm run dev` (`tsc --watch`) running while you work, or rebuild by hand after every change.
37
- - **`npm install` in a consumer drops the link.** It replaces the symlink with the registry copy, so the consumer quietly falls back to the published version. Re-link after any install. `ls -l <consumer>/node_modules/@soltech/fluid-common` tells you which you have: a symlink, or a real directory.
38
-
39
- ### Publishing Flow
40
- The correct sequence before publishing a new version:
41
- 1. Make all code changes in `src/`.
42
- 2. Bump `version` in `package.json`.
43
- 3. Run `npm i` (updates `package-lock.json`).
44
- 4. Commit all changes (`src/`, `package.json`, `package-lock.json`).
45
- 5. Push the commit: `git push`.
46
- 6. Publish to npm: `npm publish`. Its `prepublishOnly` script rebuilds `lib/` first, so the package never ships stale compiled output.
47
-
48
- Do **not** use `npm run pub` as a single command — it pushes *after* publishing, which means npm gets the package before git has a clean commit.
49
-
50
- Consumers must pin an **exact** version (`"1.10.0"`), never a caret range (`"^1.10.0"`). Branch-specific prereleases are common here, so a range can pull in a version the consumer was never tested against.
51
-
52
- Before final proposal on code changes:
53
- 1. Run `npm run lint`.
54
- 2. Run `npm run build`.
55
- 3. If you did not run them, say so.
56
-
57
- ## Coding Style & Conventions
58
- - Follow `.editorconfig` (tabs, max line length 140).
59
- - Follow ESLint config `@soltech`.
60
-
61
- ## Testing
62
- - There is no testing in this repo.
63
-
64
- ## Versioning
65
- - When changes are meant for release, bump `package.json` version per README guidance.
66
-
67
- ## Pull Requests
68
-
69
- When creating PRs, always include a Shortcut ticket reference in the PR body using the `[sc-NNNNN]` format so it automatically links to the ticket:
70
-
71
- ```
72
- [sc-17649](https://app.shortcut.com/soltech/story/17649/ticket-title-slug)
73
- ```
74
-
75
- ### PR description scope
76
-
77
- - The PR description must reflect **all changes in the branch**, not just the most recent commit. Run `git log main..HEAD` and review the full diff before writing or updating the description.
78
- - When a ticket spans multiple repos (e.g. a type/enum change here in `fluid-common` that also requires updates in `fluid-api`, `fluid-widget`, or `fluid-payments`), list the related repos and their PRs in the description so reviewers have the full picture. Name each repo, briefly describe what changed, and cross-link the corresponding PRs.
package/src/bonus.ts DELETED
@@ -1,12 +0,0 @@
1
- export interface AvailableBonusWithPaymentMethods {
2
- code: string;
3
- paymentMethodFilter?: {
4
- applyTo?: BonusPaymentMethod[];
5
- excludeFrom?: BonusPaymentMethod[];
6
- }
7
- }
8
-
9
- export interface BonusPaymentMethod {
10
- providerType: string;
11
- service?: string;
12
- }
package/src/index.ts DELETED
@@ -1,7 +0,0 @@
1
- export * from './wallet.js';
2
- export * from './wallet-config-keys.js';
3
- export * from './payment-methods.js';
4
- export * from './transactions.js';
5
- export * from './user.js';
6
- export * from './bonus.js';
7
- export * from './tracking.js';
@@ -1,165 +0,0 @@
1
- import type { WindowRedirectType } from './transactions.js';
2
-
3
- export enum PaymentType {
4
- APPLE_PAY = 'ApplePay',
5
- BANK_TRANSFER = 'BankTransfer',
6
- CREDIT_CARD = 'CreditCard',
7
- CRYPTO = 'Crypto',
8
- EWALLET = 'EWallet',
9
- VOUCHER = 'Voucher'
10
- }
11
-
12
- export type TransactionStatusSource = 'gateway' | 'fluid';
13
-
14
- export interface TransactionStatusCheck {
15
- url: string;
16
- intervalSeconds: number;
17
- source?: TransactionStatusSource;
18
- }
19
-
20
- export interface AllPaymentMethods {
21
- recentPaymentMethods: RecentMethod[];
22
- paymentMethods: PaymentMethod[];
23
- }
24
-
25
- export interface AllPaymentMethodsByTransactionType {
26
- deposit: AllPaymentMethods,
27
- withdrawal: AllPaymentMethods
28
- }
29
-
30
- export interface PaymentMethod {
31
- id: string;
32
- name: string;
33
- paymentGatewayId: string;
34
- description: string;
35
- termsAndConditions: string;
36
- logo: PaymentMethodLogo;
37
- logoLight?: PaymentMethodLogo;
38
- minAmount: number;
39
- maxAmount: number;
40
- info: string;
41
- paymentType: PaymentType;
42
- inputFields?: InputField[];
43
- storedMethodInputFields?: InputField[];
44
- bonusCodes?: string[];
45
- instructions?: string;
46
- withdrawalInstructions?: string;
47
- fees?: PaymentMethodFees;
48
- windowRedirectType?: WindowRedirectType;
49
- voucherAmounts?: number[];
50
- depositHandledByHostSite?: boolean;
51
- withdrawalHandledByHostSite?: boolean;
52
- transactionStatusCheck?: TransactionStatusCheck;
53
- finalTransactionResultCheckEnabled?: boolean;
54
- encryptionSettings?: EncryptionSettings;
55
- hostedFields?: HostedFieldsSettings;
56
- deviceProtection?: DeviceProtectionSettings;
57
- }
58
-
59
- /** Its presence is also how the client decides the gateway behind this method profiles at all. */
60
- export interface DeviceProtectionSettings {
61
- merchantId: string;
62
- env: string;
63
- }
64
-
65
- export interface EncryptionSettings {
66
- encryptionType: EncryptionType;
67
- expiryDateEncryptionMode: ExpiryDateEncryptionMode;
68
- encryptCardholderName: boolean;
69
- }
70
-
71
- export type HostedFieldsSettings = CardValuesSettings | CardTokenSettings;
72
-
73
- interface HostedFieldsBase {
74
- // Its presence is also how the client decides a method uses hosted fields at all.
75
- url: string;
76
- }
77
-
78
- export interface CardValuesSettings extends HostedFieldsBase {
79
- // Absent selects this protocol, so responses composed before the field existed keep working.
80
- protocol?: HostedFieldsProtocol.CARD_VALUES;
81
- }
82
-
83
- export interface CardTokenSettings extends HostedFieldsBase {
84
- protocol: HostedFieldsProtocol.CARD_TOKEN;
85
- params: CardTokenParams;
86
- }
87
-
88
- export interface CardTokenParams {
89
- merchantId: string;
90
- env: string;
91
- // Set only on a stored method, whose fields re-verify a card rather than collect a new one.
92
- token?: string;
93
- }
94
-
95
- // Which message contract the client must speak to the hosted fields, not which gateway
96
- // is behind them — the gateway's identity stays server-side.
97
- export enum HostedFieldsProtocol {
98
- CARD_VALUES = 'CardValues',
99
- CARD_TOKEN = 'CardToken'
100
- }
101
-
102
- export enum EncryptionType {
103
- NO_ENCRYPTION = 'NO_ENCRYPTION',
104
- RSA_PKCS1 = 'RSA_PKCS1', // RSA with PKCS#1 v1.5 padding (jsencrypt default)
105
- RSA_OAEP = 'RSA_OAEP', // RSA with OAEP padding (crypto/Web Crypto)
106
- SHA384_SIGNATURE = 'SHA384_SIGNATURE' // SHA-384-based signature (headers)
107
- }
108
-
109
- export enum ExpiryDateEncryptionMode {
110
- NONE = 'NONE',
111
- SEPARATE_FIELDS = 'SEPARATE_FIELDS',
112
- SINGLE_FIELD = 'SINGLE_FIELD'
113
- }
114
-
115
- export type PaymentMethodFees = {
116
- fixed?: number;
117
- percentage?: number;
118
- applyToRange?: {
119
- min?: number;
120
- max?: number;
121
- }
122
- }[];
123
-
124
- export interface PaymentMethodLogo {
125
- height: number;
126
- url: string;
127
- width: number;
128
- }
129
-
130
- export interface InputField {
131
- paramName: string;
132
- format: string;
133
- text: string;
134
- placeholderText: string;
135
- errorText: string;
136
- optional: boolean;
137
- options: InputFieldOption[];
138
- prefillKey?: string;
139
- removePrefixPlusSign?: boolean;
140
- relatesTo?: string;
141
- showForValues?: string[];
142
- isPassword?: boolean;
143
- }
144
-
145
- export interface InputFieldOption {
146
- label: string;
147
- code: string;
148
- relatesTo?: string;
149
- showForValues?: string[];
150
- }
151
-
152
- export enum RecentMethodMaskedAccountFormat {
153
- DEFAULT = 'Default',
154
- LAST_8_DIGITS = 'Last8Digits',
155
- FULL_VALUE = 'FullValue',
156
- NOTHING = 'Nothing'
157
- }
158
-
159
- export interface RecentMethod extends PaymentMethod {
160
- accountId: string;
161
- maskedAccount: string;
162
- lastSuccess?: string;
163
- expiryDate?: string;
164
- maskedAccountFormat?: RecentMethodMaskedAccountFormat;
165
- }
package/src/tracking.ts DELETED
@@ -1,36 +0,0 @@
1
- export interface TrackingEvent {
2
- eventId: string;
3
- data: object;
4
- }
5
-
6
- export interface TimedTrackingEvent extends TrackingEvent {
7
- // Milliseconds between the event and the send. Outside `data` so a replayed request hashes the same.
8
- clientOffsetMs: number;
9
- }
10
-
11
- export interface TrackEventBatch {
12
- // Oldest first.
13
- events: TimedTrackingEvent[];
14
- }
15
-
16
- export interface TrackingEventData {
17
- id: string;
18
- event: string;
19
- operatorId?: string;
20
- timestamp?: string | number | Date;
21
- activityId?: string;
22
- originalActivityId?: string;
23
- bonusesOffered?: boolean;
24
- country?: string;
25
- sessionId?: string;
26
- userAgent?: string;
27
- userId?: string;
28
-
29
- [key: string]: unknown;
30
- }
31
-
32
- export type TrackingEventDataEnvelope = {
33
- id: string;
34
- environment: 'production' | 'staging' | 'demo';
35
- body: TrackingEventData;
36
- };