Session API

[alessandrobellesia]

fix!: align Session API with official Satispay specification

BREAKING CHANGE: Session event operations updated

• Changed type → operation in session events
• Changed SessionEventType → SessionEventOperation
• Replaced 'ADD_ITEM'/'REMOVE_ITEM' with 'ADD'/'REMOVE'
• Removed 'UPDATE_TOTAL' operation (not supported by API)
• Made currency field mandatory in SessionEventCreateBody
• Fixed Pre-Authorized Payment Tokens documentation
• Removed duplicate "Create a Payment" section in README
• Added E2E tests for fund lock payments

Summary by CodeRabbit

• Breaking Changes

  • Session events API updated: field type renamed to operation with new values ('ADD', 'REMOVE')
  • Currency field now mandatory for session events

• New Features

  • Added end-to-end tests for fund lock payments
  • Expanded Pre-Authorized Payment Tokens documentation with complete usage workflows

• Bug Fixes

  • Session types and operations now correctly align with Satispay API specifications

• Documentation

  • Updated examples and README to reflect new session event structure
  • Test coverage increased to 94.82%

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR implements breaking changes to the Session API to align with official Satispay documentation. The session event type field is renamed to operation with simplified values (ADD/REMOVE), currency becomes mandatory, and amount_unit becomes required. Documentation, examples, tests, and a new E2E test for fund lock payments are updated accordingly.

Changes

Cohort / File(s)	Summary
Type & API Definitions src/types.ts	Renames SessionEventType to SessionEventOperation; narrows values from 'ADD_ITEM' | 'REMOVE_ITEM' | 'UPDATE_TOTAL' to 'ADD' | 'REMOVE'; updates SessionEventCreateBody to replace type with operation, makes amount_unit required, and adds mandatory currency field.
Documentation & Changelog CHANGELOG.md, README.md	Adds v0.0.4 unreleased section documenting breaking Session API changes; expands Pre-Authorized Payment Tokens section; updates Session event examples to use new operation-based payloads; updates test coverage metrics from 79.45% to 94.82%; corrects related documentation and examples.
Examples & Source examples/pos-session.ts, src/Session.ts	Replaces Session event payloads from type: 'ADD_ITEM' | 'REMOVE_ITEM' to operation: 'ADD' | 'REMOVE'; adds mandatory currency: 'EUR' field to all createEvent calls; updates inline code examples to reflect new payload shape.
Unit Tests tests/Session.test.ts	Updates all Session.createEvent test cases to use new operation-based payloads with operation field, currency field, and amount_unit as required; adjusts assertions and test naming to reflect API changes; preserves request URL and signature handling.
E2E Tests tests/e2e/session.e2e.test.ts	Adds new end-to-end test suite for fund lock payment creation and retrieval; tests verify fund lock payment properties (id, amount_unit, currency, status, code_identifier) across creation and fetch operations; tests conditionally skip based on environment readiness.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

Areas requiring extra attention:

• src/types.ts — Core breaking change; verify all dependent code properly references renamed types and operations
• tests/Session.test.ts — Comprehensive test updates; confirm all assertions align with new payload structure and that request handling remains correct
• examples/pos-session.ts and README.md — Cross-verify that documented examples match the new API signatures and field requirements
• tests/e2e/session.e2e.test.ts — New test coverage; validate fund lock payment flow and environment-based skip logic work as intended

Poem

🐰 Hops with glee through API lanes,
Operations now flow cleaner—ADD and REMOVE the chains!
Currency mandatory, amount required with care,
Fund lock payments tested, docs refreshed everywhere! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title check	❓ Inconclusive	The title 'Session API' is vague and generic, failing to capture the main breaking changes (field/enum renames, operation updates, mandatory currency field) that define this significant changeset.	Use a more descriptive title that reflects the breaking changes, such as 'Align Session API with official Satispay specification' or 'Update Session event operations and fields (type→operation, add currency requirement)'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/session-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (6)

CHANGELOG.md (1)

8-26: Call out amount_unit requirement as part of the breaking change

Changelog correctly documents the rename to operation and the new mandatory currency field, but SessionEventCreateBody.amount_unit is now also required in src/types.ts. Consider adding a bullet explicitly stating that amount_unit became mandatory to fully describe the breaking surface for session events.

src/Session.ts (1)

128-158: Clarify wording now that only ADD/REMOVE operations exist

The examples correctly use operation: 'ADD' | 'REMOVE' and include currency, matching the new types. The JSDoc remark above still says “add, remove, or update items,” which might suggest a third UPDATE operation that no longer exists. Consider rephrasing to something like “Events are used to add or remove items in a POS session; each event updates the total amount…” to avoid implying an unsupported operation.

tests/e2e/session.e2e.test.ts (1)

1-67: Well-scoped E2E test; condition helpers could be simplified

The fund lock E2E flow (create → assert fields → get → assert fields) is coherent and guarded behind environment checks, which is appropriate for real API calls. Since hasAuthenticationKeys() currently just proxies canRunE2ETests(), you could simplify the describe.skipIf condition to a single helper or differentiate their responsibilities, but that’s purely cosmetic.

tests/Session.test.ts (1)

176-281: Session.createEvent tests cover new payload shape well

The updated tests for createEvent correctly:

• Use operation: 'ADD' | 'REMOVE' instead of the old type field.
• Include mandatory currency: 'EUR'.
• Verify both full payloads and nested metadata where relevant.

If you want to harden the “with metadata” case further, you could extend the expect.objectContaining to also assert operation and currency, but given the other tests already cover those fields, this is optional.

README.md (2)

15-16: Updated bundle size notes are consistent

The “Lightweight” feature and “Why Zero Dependencies?” sections now both reference a 268KB bundle, which keeps the messaging consistent. Just keep in mind these hard-coded numbers will need updating if the bundle grows again.

Also applies to: 600-602

---

544-544: Coverage numbers updated; ensure they stay in sync with reports

The coverage line reflects significantly higher coverage (94.82%). Looks good, but remember to refresh this value periodically from actual reports so it doesn’t drift.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bb58c34 and 1b6a569.

📒 Files selected for processing (7)

• CHANGELOG.md (2 hunks)
• README.md (5 hunks)
• examples/pos-session.ts (1 hunks)
• src/Session.ts (2 hunks)
• src/types.ts (2 hunks)
• tests/Session.test.ts (2 hunks)
• tests/e2e/session.e2e.test.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

tests/e2e/session.e2e.test.ts (1)

tests/setup.ts (2)

• canRunE2ETests (49-55)
• hasAuthenticationKeys (61-63)

tests/Session.test.ts (2)

src/types.ts (2)

• SessionEventCreateBody (317-323)
• SessionResponse (295-305)

src/Session.ts (1)

• Session (41-174)

examples/pos-session.ts (1)

src/Session.ts (1)

• Session (41-174)

🔇 Additional comments (7)

CHANGELOG.md (1)

88-90: Version compare links look consistent

The new compare links for v0.0.4, v0.0.3, and v0.0.2 are coherent with the existing style and should work as expected.

src/Session.ts (1)

27-32: Session open example aligned with new API

Example now uses operation: 'ADD' and includes currency: 'EUR', consistent with SessionEventCreateBody. No issues here.

src/types.ts (2)

66-68: Session event operation type matches documented surface

SessionEventOperation = 'ADD' | 'REMOVE' reflects the simplified operation set and aligns with the updated examples/tests. Looks good.

---

317-323: SessionEventCreateBody shape is coherent with usage

Requiring operation, amount_unit, and currency here matches how events are created in Session.createEvent, the examples, and the tests. Aside from ensuring the changelog fully documents these required fields (already noted there), the type definition itself looks solid.

README.md (2)

227-264: Pre-Authorized Payment Tokens docs nicely aligned with types

This section now clearly documents:

• Creation parameters (reason, callback_url, redirect_url).
• Retrieval and update (including status: 'CANCELED').
• Downstream usage in Payment.create with flow: 'PRE_AUTHORIZED' and token: token.token.
• Status semantics and the “use token, not id” guidance.

All of this matches the corresponding type definitions and intended flow.

---

315-331: Session examples match the new SessionEventCreateBody

The Session examples now use:

• operation: 'ADD' | 'REMOVE' instead of the old type values.
• Explicit currency: 'EUR' on each event.
• amount_unit in cents as elsewhere.

This keeps the README in sync with SessionEventCreateBody and the runtime behavior.

examples/pos-session.ts (1)

70-111: POS session example correctly demonstrates ADD/REMOVE operations

The example’s Session.createEvent calls now use operation: 'ADD' | 'REMOVE' with amount_unit in cents and currency: 'EUR', matching the new API and types. The item/discount amounts and comments are consistent, so this should be a very clear reference for integrators.