npm package: @flowpay-io/shared
Description: Flowpay SDK shared types and utilities
Author: Flowpay
Latest version: 1.2.0

# @flowpay-io/shared

Shared TypeScript type definitions and utilities for Flowpay SDK packages.

## Installation

```bash
pnpm add @flowpay-io/shared
```

## Launch payloads

`FlowpayLaunchPayload` is a union of **merchant** and **customer** launch payloads. Use the right shape depending on whether you are logging in a new or previously activated merchant or an existing Flowpay customer you previously activated.

Later in the process, use different integrationType setting based on the payload type (merchant or customer), passed as parameter to the SDK functions or with manual implementation, add it directly in the fp:LOGIN envelope in the meta field.

**`locale`** is part of **`FlowpayEnvelopeMeta`** on `fp:LOGIN` for **initial login** (`meta.reason: "initial"`) only. It is a host hint for the embedded UI language (e.g. `en`, `cs`) and is **not** included in the signed launch payload JSON. Session refresh omits it; the embedded app persists language after first login.

### Merchant launch payload

For logging in a new or previously activated merchant:

```typescript
import type { MerchantLaunchPayload } from "@flowpay-io/shared/types";
import { IsoCountryCode } from "@flowpay-io/shared/types";

const payload: MerchantLaunchPayload = {
  country: IsoCountryCode.CZ,
  merchantId: "merchant-123",
  partnerCode: "partner-abc",
  regNum: "12345678",
  userId: "user-456",
  createdAt: new Date().toISOString(),
  // optional: pre-fill and skip in-app input
  email: "user@example.com",
  phone: "+420123456789",
  // optional: merchant branches (e-shops, locations, etc.)
  tenants: [{ id: "branch-1", name: "Main store" }],
};
```

### Customer launch payload

For logging in an existing Flowpay customer entity (previously activated by the partner):

```typescript
import type { CustomerLaunchPayload } from "@flowpay-io/shared/types";

const payload: CustomerLaunchPayload = {
  partnerCode: "partner-abc",
  customerId: "flowpay-customer-id",
  userId: "user-456",
  repId: "rep-123",
  createdAt: new Date().toISOString(),
};
```

When using `@flowpay-io/embed-core`, `createdAt` can be omitted; the client sets it automatically if `autoSetCreatedAt` is enabled (default).

### Utilities

The package also provides utility functions:

```typescript
import { getCanonicalPayloadString } from "@flowpay-io/shared/utils";

// Merchant payload: integrationType defaults to "merchant" when omitted
const canonicalMerchantPayload = getCanonicalPayloadString(payload);

// Customer payload: explicitly pass "customer" as the integrationType
const canonicalCustomerPayload = getCanonicalPayloadString(
  customerPayload,
  "customer",
);
```

### Canonical form and signatures

`getCanonicalPayloadString` produces a **stable JSON string** used for HMAC signature generation and verification. The **field order** in that string is fixed:

- **Customer payload:** alphabetical key order: `createdAt`, `customerId`, `partnerCode`, `repId`, `userId`.
- **Merchant payload:** alphabetical key order for top-level fields; `tenants` (when present) sorted by `id`.

Any change to this ordering would change the serialized string and break signature validation. Backends that reconstruct or verify the payload must use the same canonical order; the implementation in `packages/shared/src/utils.ts` is the source of truth.

## Links

- **Homepage**: [https://www.flowpay.io](https://www.flowpay.io)
- **Documentation**: [https://developers.flowpay.io](https://developers.flowpay.io)