feat: add SetupAgreement list to SetupAction for document consent (ORD-1856)

.changeset/ord-1856.md

@@ -0,0 +1,6 @@
+---
+"@lifi/perps-types": minor
+"@lifi/perps-sdk": minor
+---
+
+Add `SetupAgreement` and the optional `SetupAction.agreements` list, which names the documents a user must accept before a setup step executes.

packages/perps-sdk/src/services/getProviders.unit.spec.ts

@@ -1,6 +1,11 @@
+import type { ProvidersResponse, SetupAgreement } from '@lifi/perps-types'
+import { HttpResponse, http } from 'msw'
 import { describe, expect, it } from 'vitest'
-import { mockProviders } from '../../test/handlers.js'
-import { createPerpsClient } from '../client/createPerpsClient.js'
+import { mockProviders, server } from '../../test/handlers.js'
+import {
+  createPerpsClient,
+  DEFAULT_API_URL,
+} from '../client/createPerpsClient.js'
 import { getProviders } from './getProviders.js'
 
 describe('getProviders', () => {
@@ -32,6 +37,30 @@ describe('getProviders', () => {
     ])
   })
 
+  it('passes setup agreements through unchanged', async () => {
+    const agreements: SetupAgreement[] = [
+      { title: 'Terms of Use', url: 'https://example.invalid/terms' },
+      { title: 'Privacy Policy', url: 'https://example.invalid/privacy' },
+    ]
+    const [provider] = mockProviders.providers
+    const fixture: ProvidersResponse = {
+      providers: [
+        {
+          ...provider,
+          setup: [{ ...provider.setup[0], agreements }],
+        },
+      ],
+    }
+    server.use(
+      http.get(`${DEFAULT_API_URL}/providers`, () => HttpResponse.json(fixture))
+    )
+
+    const result = await getProviders(client)
+
+    expect(result.providers[0].setup[0].agreements).toEqual(agreements)
+    expect(result).toEqual(fixture)
+  })
+
   it('should support AbortSignal', async () => {
     const controller = new AbortController()
     controller.abort()

packages/perps-types/src/index.unit.spec.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
 import * as perpsTypes from './index.js'
+import type { SetupAgreement } from './providers.js'
 
 describe('@lifi/perps-types runtime surface', () => {
   it('exports no function; runtime helpers belong in @lifi/perps-sdk', () => {
@@ -9,4 +10,8 @@ describe('@lifi/perps-types runtime surface', () => {
 
     expect(functions).toEqual([])
   })
+
+  it('exports SetupAgreement', () => {
+    expectTypeOf<perpsTypes.SetupAgreement>().toEqualTypeOf<SetupAgreement>()
+  })
 })

packages/perps-types/src/providers.ts

@@ -104,6 +104,17 @@ export interface SetupOption<T extends ActionType = ActionType> {
   default?: true
 }
 
+/**
+ * A document, such as terms of use or a privacy policy, that the user must
+ * accept before a setup step executes.
+ *
+ * @public
+ */
+export interface SetupAgreement {
+  title: string
+  url: string
+}
+
 /**
  * One `Provider.setup` step. A choice step (`options !== null`) declares no
  * `params`: each option carries its own bound params.
@@ -115,6 +126,12 @@ export interface SetupAction extends ProviderAction {
   options: SetupOption[] | null
   /** A `Provider.actions` entry that undoes the satisfied step, or `null`. */
   revoke: ActionType | null
+  /**
+   * Documents the step asks the user to accept. A UI must show each entry as
+   * a link with its own checkbox, and must execute the step only after the
+   * user accepts all entries.
+   */
+  agreements?: SetupAgreement[]
 }
 
 /**

packages/perps-types/src/providers.unit.spec.ts

@@ -21,6 +21,7 @@ import type {
   ProviderCategory,
   ProviderFunding,
   SetupAction,
+  SetupAgreement,
   SetupOption,
   TradeNotice,
 } from './providers.js'
@@ -435,6 +436,13 @@ type _SetupOptionDescriptionShape = Expect<
 type _SetupOptionDescriptionIsOptional = Expect<
   Equals<Extract<RequiredKeys<SetupOption>, 'description'>, never>
 >
+type _SetupAgreementKeys = Expect<Equals<keyof SetupAgreement, 'title' | 'url'>>
+type _SetupAgreementsShape = Expect<
+  Equals<SetupAction['agreements'], SetupAgreement[] | undefined>
+>
+type _SetupAgreementsIsOptional = Expect<
+  Equals<Extract<RequiredKeys<SetupAction>, 'agreements'>, never>
+>
 type _SignerIsSingle = Expect<Equals<ProviderAction['signer'], PerpsSigner>>
 type _RelayShape = Expect<Equals<ProviderAction['relay'], ActionRelay>>
 type _NoOptionsField = Expect<Equals<Extract<keyof Provider, 'options'>, never>>
@@ -613,6 +621,9 @@ export type _TypeAssertions = [
   _SetupOptionBindsParams,
   _SetupOptionDescriptionShape,
   _SetupOptionDescriptionIsOptional,
+  _SetupAgreementKeys,
+  _SetupAgreementsShape,
+  _SetupAgreementsIsOptional,
   _SignerIsSingle,
   _RelayShape,
   _NoOptionsField,