@dalmore/api-contracts 1.0.5 → 1.0.6

package/src/common/types/webhook.types.ts

@@ -0,0 +1,588 @@
+import { z } from 'zod';
+import { PersonaStatus } from './common.types';
+
+export const WebhookReceived = z.object({
+  received: z.boolean(),
+});
+export type WebhookReceived = z.infer<typeof WebhookReceived>;
+
+// https://docs.stripe.com/api/events/object
+export const StripeWebhookEvent = z.object({
+  id: z.string().nullable().optional(),
+  object: z.string().nullable().optional(),
+  account: z.string().nullable().optional(),
+  api_version: z.string().nullable().optional(),
+  created: z.number().nullable().optional(),
+  data: z
+    .object({
+      object: z
+        .object({
+          id: z.string().nullable().optional(),
+          object: z.string().nullable().optional(),
+          application: z.string().nullable().optional(),
+          automatic_payment_methods: z
+            .object({
+              allow_redirects: z.string().nullable().optional(),
+              enabled: z.boolean().nullable().optional(),
+            })
+            .nullable()
+            .optional(),
+          cancellation_reason: z.string().nullable().optional(),
+          client_secret: z.string().nullable().optional(),
+          created: z.number().nullable().optional(),
+          customer: z.string().nullable().optional(),
+          description: z.string().nullable().optional(),
+          flow_directions: z.string().nullable().optional(),
+          last_setup_error: z.object({}).nullable().optional(),
+          latest_attempt: z.string().nullable().optional(),
+          livemode: z.boolean().nullable().optional(),
+          mandate: z.string().nullable().optional(),
+          metadata: z.record(z.any()).nullable().optional(),
+          next_action: z.string().nullable().optional(),
+          on_behalf_of: z.string().nullable().optional(),
+          payment_method: z.string().nullable().optional(),
+          payment_method_options: z
+            .object({
+              acss_debit: z
+                .object({
+                  currency: z.string().nullable().optional(),
+                  mandate_options: z
+                    .object({
+                      interval_description: z.string().nullable().optional(),
+                      payment_schedule: z.string().nullable().optional(),
+                      transaction_type: z.string().nullable().optional(),
+                    })
+                    .nullable()
+                    .optional(),
+                  verification_method: z.string().nullable().optional(),
+                })
+                .nullable()
+                .optional(),
+              card: z
+                .object({
+                  installments: z.any().nullable().optional(),
+                  mandate_options: z.any().nullable().optional(),
+                  network: z.string().nullable().optional(),
+                  request_three_d_secure: z.string().nullable().optional(),
+                })
+                .nullable()
+                .optional(),
+              link: z
+                .object({
+                  persistent_token: z.string().nullable().optional(),
+                })
+                .nullable()
+                .optional(),
+              us_bank_account: z
+                .object({
+                  financial_connections: z
+                    .object({
+                      permissions: z.array(z.string()).nullable().optional(),
+                      prefetch: z.array(z.string()).nullable().optional(),
+                    })
+                    .nullable()
+                    .optional(),
+                  mandate_options: z.record(z.any()).nullable().optional(),
+                  verification_method: z.string().nullable().optional(),
+                })
+                .nullable()
+                .optional(),
+            })
+            .nullable()
+            .optional(),
+          payment_method_types: z.array(z.string()).nullable().optional(),
+          single_use_mandate: z.string().nullable().optional(),
+          status: z.string().nullable().optional(),
+          usage: z.string().nullable().optional(),
+          amount: z.number().nullable().optional(),
+          amount_capturable: z.number().nullable().optional(),
+          amount_details: z.record(z.any()).nullable().optional(),
+          amount_received: z.number().nullable().optional(),
+          application_fee_amount: z.number().nullable().optional(),
+          canceled_at: z.number().nullable().optional(),
+          capture_method: z.string().nullable().optional(),
+          confirmation_method: z.string().nullable().optional(),
+          currency: z.string().nullable().optional(),
+          invoice: z.string().nullable().optional(),
+          last_payment_error: z.record(z.any()).nullable().optional(),
+          latest_charge: z.string().nullable().optional(),
+          payment_method_configuration_details: z
+            .object({
+              id: z.string().nullable().optional(),
+              parent: z.string().nullable().optional(),
+            })
+            .nullable()
+            .optional(),
+          processing: z.record(z.any()).nullable().optional(),
+          receipt_email: z.string().nullable().optional(),
+          review: z.string().nullable().optional(),
+          setup_future_usage: z.string().nullable().optional(),
+          shipping: z.record(z.any()).nullable().optional(),
+          source: z.string().nullable().optional(),
+          statement_descriptor: z.string().nullable().optional(),
+          statement_descriptor_suffix: z.string().nullable().optional(),
+          transfer_data: z.record(z.any()).nullable().optional(),
+          transfer_group: z.string().nullable().optional(),
+        })
+        .nullable()
+        .optional(),
+    })
+    .nullable()
+    .optional(),
+  livemode: z.boolean().nullable().optional(),
+  pending_webhooks: z.number().nullable().optional(),
+  request: z
+    .object({
+      id: z.string().nullable().optional(),
+      idempotency_key: z.string().nullable().optional(),
+    })
+    .nullable()
+    .optional(),
+  type: z.string().nullable().optional(),
+  context: z.string().nullable().optional(),
+});
+export type StripeWebhookEvent = z.infer<typeof StripeWebhookEvent>;
+
+/**
+ * BoldSign webhook event structure
+ * @see https://developers.boldsign.com/webhooks/sample-event-data/?region=us
+ *
+ * Event types include:
+ * - Signed: When a signer completes signing
+ * - Declined: When a signer declines to sign
+ * - SenderIdentityVerified: When a sender identity is verified
+ * - SenderIdentityDenied: When a sender identity is denied
+ * - SenderIdentityRevoked: When a sender identity is revoked
+ * - SenderIdentityDeleted: When a sender identity is deleted
+ */
+export const BoldsignWebhookEvent = z.object({
+  event: z.object({
+    id: z.string().optional(),
+    eventType: z.string(),
+    created: z.number().optional(),
+    clientId: z.string().optional(),
+    environment: z.string().optional(),
+  }),
+  data: z.object({
+    object: z.string().optional(),
+    documentId: z.string().optional(),
+    messageTitle: z.string().optional(),
+    documentDescription: z.string().optional(),
+    status: z.string().optional(),
+    email: z.string().optional(), // For SenderIdentity events
+    senderDetail: z
+      .object({
+        name: z.string().optional(),
+        emailAddress: z.string().optional(),
+      })
+      .optional(),
+    signerDetails: z
+      .array(
+        z.object({
+          signerName: z.string().optional(),
+          signerRole: z.string().optional(),
+          signerEmail: z.string().optional(),
+          status: z.string().optional(),
+          signerOrder: z.number().optional(),
+          formFields: z
+            .array(
+              z.object({
+                id: z.string().optional(),
+                name: z.string().optional(),
+                fieldType: z.string().optional(),
+                value: z.any().optional(),
+                isRequired: z.boolean().optional(),
+              }),
+            )
+            .optional(),
+        }),
+      )
+      .optional(),
+    metaData: z.record(z.string(), z.any()).optional(),
+  }),
+});
+export type BoldsignWebhookEvent = z.infer<typeof BoldsignWebhookEvent>;
+
+/**
+ * Sample event data:
+ * https://docs.withpersona.com/docs/webhooks
+ * We are only interested in the inquiry and inquiry session events
+ * because we subscribe only to inquiry events
+ * https://docs.withpersona.com/docs/events
+ */
+const fieldValueSchema = z.object({
+  type: z.string(),
+  value: z.any().optional(),
+});
+
+const behaviorsSchema = z.object({
+  'autofill-cancels': z.number().nullable().optional(),
+  'autofill-starts': z.number().nullable().optional(),
+  'completion-time': z.number().nullable().optional(),
+  'devtools-open': z.boolean().nullable().optional(),
+  'distraction-events': z.number().nullable().optional(),
+  'hesitation-baseline': z.number().nullable().optional(),
+  'hesitation-count': z.number().nullable().optional(),
+  'hesitation-percentage': z.number().nullable().optional(),
+  'hesitation-time': z.number().nullable().optional(),
+  'request-spoof-attempts': z.number().nullable().optional(),
+  'shortcut-copies': z.number().nullable().optional(),
+  'shortcut-pastes': z.number().nullable().optional(),
+  'user-agent-spoof-attempts': z.number().nullable().optional(),
+  'behavior-threat-level': z.string().nullable().optional(),
+});
+
+const relationshipDataSchema = z.object({
+  type: z.string(),
+  id: z.string(),
+});
+
+const relationshipSchema = z.object({
+  data: z.union([relationshipDataSchema, z.null()]),
+});
+
+const inquiryAttributesSchema = z
+  .object({
+    behaviors: behaviorsSchema.optional(),
+    fields: z.record(fieldValueSchema).optional(),
+    status: z.nativeEnum(PersonaStatus),
+    'reference-id': z.string().nullable().optional(),
+    note: z.string().nullable().optional(),
+    creator: z.string().nullable().optional(),
+    'reviewer-comment': z.string().nullable().optional(),
+    'created-at': z.string().datetime().nullable().optional(),
+    'started-at': z.string().datetime().nullable().optional(),
+    'expires-at': z.string().datetime().nullable().optional(),
+    'completed-at': z.string().datetime().nullable().optional(),
+    'failed-at': z.string().datetime().nullable().optional(),
+    'marked-for-review-at': z.string().datetime().nullable().optional(),
+    'decisioned-at': z.string().datetime().nullable().optional(),
+    'expired-at': z.string().datetime().nullable().optional(),
+    'redacted-at': z.string().datetime().nullable().optional(),
+    'updated-at': z.string().datetime().nullable().optional(),
+    'previous-step-name': z.string().nullable().optional(),
+    'next-step-name': z.string().nullable().optional(),
+    'name-first': z.string().nullable().optional(),
+    'name-middle': z.string().nullable().optional(),
+    'name-last': z.string().nullable().optional(),
+    birthdate: z.string().nullable().optional(),
+    'address-street-1': z.string().nullable().optional(),
+    'address-street-2': z.string().nullable().optional(),
+    'address-city': z.string().nullable().optional(),
+    'address-subdivision': z.string().nullable().optional(),
+    'address-subdivision-abbr': z.string().nullable().optional(),
+    'address-postal-code': z.string().nullable().optional(),
+    'address-postal-code-abbr': z.string().nullable().optional(),
+    'social-security-number': z.string().nullable().optional(),
+    'identification-number': z.string().nullable().optional(),
+    'email-address': z.string().nullable().optional(),
+    'phone-number': z.string().nullable().optional(),
+    tags: z.array(z.string()).nullable().optional(),
+  })
+  .passthrough();
+
+const accountFieldsSchema = z.object({
+  name: z.object({
+    type: z.string(),
+    value: z.object({
+      first: fieldValueSchema,
+      middle: fieldValueSchema,
+      last: fieldValueSchema,
+    }),
+  }),
+  address: z.object({
+    type: z.string(),
+    value: z.object({
+      street_1: fieldValueSchema,
+      street_2: fieldValueSchema,
+      city: fieldValueSchema,
+      subdivision: fieldValueSchema,
+      postal_code: fieldValueSchema,
+      country_code: fieldValueSchema,
+    }),
+  }),
+  identification_numbers: z.object({
+    type: z.string(),
+    value: z.array(z.any()),
+  }),
+  birthdate: fieldValueSchema,
+  phone_number: fieldValueSchema,
+  email_address: fieldValueSchema,
+  selfie_photo: fieldValueSchema,
+});
+
+const accountSchema = z.object({
+  type: z.string(),
+  id: z.string(),
+  attributes: z.object({
+    'reference-id': z.string().optional(),
+    'created-at': z.string().datetime().optional(),
+    'updated-at': z.string().datetime().optional(),
+    'redacted-at': z.string().datetime().optional(),
+    'account-type-name': z.string().optional(),
+    fields: accountFieldsSchema,
+    'name-first': z.string().optional(),
+    'name-middle': z.string().optional(),
+    'name-last': z.string().optional(),
+    'social-security-number': z.string().optional(),
+    'address-street-1': z.string().optional(),
+    'address-street-2': z.string().optional(),
+    'address-city': z.string().optional(),
+    'address-subdivision': z.string().optional(),
+    'address-postal-code': z.string().optional(),
+    'country-code': z.string().optional(),
+    birthdate: z.string().optional(),
+    'phone-number': z.string().optional(),
+    'email-address': z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    'identification-numbers': z.record(z.any()).optional(),
+  }),
+  relationships: z.object({
+    'account-type': relationshipSchema.optional(),
+  }),
+});
+
+const inquiryRelationshipsSchema = z.object({
+  account: relationshipSchema.optional(),
+  template: relationshipSchema.optional(),
+  'inquiry-template': relationshipSchema.optional(),
+  'inquiry-template-version': relationshipSchema.optional(),
+  transaction: relationshipSchema.optional(),
+  reviewer: relationshipSchema.optional(),
+  reports: z.object({ data: z.array(z.any()) }).optional(),
+  verifications: z.object({ data: z.array(z.any()) }).optional(),
+  sessions: z.object({ data: z.array(z.any()) }).optional(),
+  documents: z.object({ data: z.array(z.any()) }).optional(),
+  selfies: z.object({ data: z.array(z.any()) }).optional(),
+});
+
+const inquirySchema = z.object({
+  type: z.string(),
+  id: z.string(),
+  attributes: inquiryAttributesSchema.optional(),
+  relationships: inquiryRelationshipsSchema.partial().optional(),
+});
+
+const inquiryTemplateSchema = z.object({
+  type: z.literal('inquiry-template'),
+  id: z.string(),
+  attributes: z.object({
+    status: z.string(),
+    name: z.string(),
+  }),
+  relationships: z.object({
+    'latest-published-version': relationshipSchema.optional(),
+  }),
+});
+
+const genericIncludedItemSchema = z.object({
+  type: z.string(),
+  id: z.string(),
+  attributes: z.record(z.any()).optional(),
+  relationships: z.record(z.any()).optional(),
+});
+
+const userSchema = z.object({
+  type: z.string(),
+  id: z.string(),
+  attributes: z.record(z.any()).optional(),
+  relationships: z.record(z.any()).optional(),
+});
+
+const inquiryTemplateVersionSchema = z.object({
+  type: z.literal('inquiry-template-version'),
+  id: z.string(),
+  attributes: z.object({
+    'name-display': z.string().optional(),
+    status: z.string().optional(),
+    'enabled-locales': z.array(z.string()).optional(),
+    'created-at': z.string().datetime().optional(),
+    'updated-at': z.string().datetime().optional(),
+    'published-at': z.string().datetime().optional(),
+    theme: z.record(z.any()).optional(),
+  }),
+  relationships: z.object({
+    'inquiry-template': relationshipSchema,
+  }),
+});
+
+// Schemas for Government ID Verification for Persona
+//https://docs.withpersona.com/reference/retrieve-a-government-id-verification
+const photoUrlSchema = z
+  .object({
+    page: z.string().optional(),
+    url: z.string().url().optional(),
+    'normalized-url': z.string().url().optional(),
+    'original-urls': z.array(z.string().url()).optional(),
+    'byte-size': z.number().optional(),
+  })
+  .optional();
+export type PhotoUrlSchema = z.infer<typeof photoUrlSchema>;
+
+const NormalizedPhotoUrlSchema = z
+  .object({
+    page: z.string().optional(),
+    url: z.string().url().optional(),
+    normalizedUrl: z.string().url().optional(),
+    originalUrls: z.array(z.string().url()).optional(),
+    byteSize: z.number().optional(),
+  })
+  .optional();
+export type NormalizedPhotoUrlSchema = z.infer<typeof NormalizedPhotoUrlSchema>;
+
+// Selfie photo schema
+const selfiePhotoSchema = z
+  .object({
+    url: z.string().url().optional(),
+    'byte-size': z.number().optional(),
+  })
+  .optional();
+
+// Attributes schema
+export const attributesSchema = z
+  .object({
+    status: z.string().optional(),
+    'created-at': z.string().datetime().optional(),
+    'created-at-ts': z.number().int().optional(),
+    'submitted-at': z.string().datetime().optional(),
+    'submitted-at-ts': z.number().int().optional(),
+    'completed-at': z.string().datetime().optional(),
+    'completed-at-ts': z.number().int().optional(),
+    'country-code': z.string().optional(),
+    checks: z.array(z.unknown()).optional(),
+    'entity-confidence-score': z.number().optional(),
+    'entity-confidence-reasons': z.array(z.string()).optional(),
+    'front-photo-url': z.string().url().optional(),
+    'back-photo-url': z.null().optional(),
+    'photo-urls': z.array(photoUrlSchema).optional(),
+    'selfie-photo': selfiePhotoSchema.optional(),
+    'selfie-photo-url': z.string().url().optional(),
+    'video-url': z.null().optional(),
+    'id-class': z.string().optional(),
+    'capture-method': z.string().optional(),
+    'name-first': z.string().optional(),
+    'name-middle': z.string().optional(),
+    'name-last': z.string().optional(),
+    'name-suffix': z.null().optional(),
+    birthdate: z.string().optional(),
+    'address-street-1': z.string().optional(),
+    'address-street-2': z.null().optional(),
+    'address-city': z.string().optional(),
+    'address-subdivision': z.string().optional(),
+    'address-postal-code': z.string().optional(),
+    'issuing-authority': z.null().optional(),
+    'issuing-subdivision': z.string().optional(),
+    nationality: z.null().optional(),
+    'document-number': z.null().optional(),
+    'visa-status': z.null().optional(),
+    'issue-date': z.string().optional(),
+    'expiration-date': z.string().optional(),
+    designations: z.array(z.unknown()).optional(),
+    birthplace: z.null().optional(),
+    endorsements: z.null().optional(),
+    height: z.null().optional(),
+    sex: z.null().optional(),
+    restrictions: z.null().optional(),
+    'vehicle-class': z.null().optional(),
+    'identification-number': z.string().optional(),
+    'from-reusable-persona': z.boolean().optional(),
+  })
+  .optional();
+
+export type AttributesSchema = z.infer<typeof attributesSchema>;
+
+// Relationship with data schema
+const relationshipWithDataSchema = z
+  .object({
+    data: relationshipDataSchema.optional(),
+  })
+  .optional();
+
+// Relationship with null data schema
+const relationshipWithNullDataSchema = z
+  .object({
+    data: z.null().optional(),
+  })
+  .optional();
+
+// Relationships schema
+const relationshipsSchema = z
+  .object({
+    inquiry: relationshipWithDataSchema.optional(),
+    template: relationshipWithNullDataSchema.optional(),
+    'inquiry-template-version': relationshipWithDataSchema.optional(),
+    'inquiry-template': relationshipWithDataSchema.optional(),
+    transaction: relationshipWithNullDataSchema.optional(),
+    'verification-template': relationshipWithDataSchema.optional(),
+    'verification-template-version': relationshipWithDataSchema.optional(),
+    document: relationshipWithDataSchema.optional(),
+  })
+  .optional();
+
+// Verification Data schema
+const verificationDataSchema = z
+  .object({
+    type: z.string().optional(),
+    id: z.string().optional(),
+    attributes: attributesSchema.optional(),
+    relationships: relationshipsSchema.optional(),
+  })
+  .optional();
+export type VerificationDataSchema = z.infer<typeof verificationDataSchema>;
+
+export const PersonaWebhookEvent = z.object({
+  data: z.object({
+    type: z.string(),
+    id: z.string(),
+    attributes: z.object({
+      name: z.enum([
+        'inquiry.created',
+        'inquiry.started',
+        'inquiry.expired',
+        'inquiry.completed',
+        'inquiry.failed',
+        'inquiry.marked-for-review',
+        'inquiry.approved',
+        'inquiry.declined',
+        'inquiry.redacted',
+        'inquiry.transitioned',
+        'inquiry-session.started',
+        'inquiry-session.expired',
+        'inquiry-session.canceled',
+        'inquiry.reusable-persona-created',
+        'inquiry.reusable-persona-updated',
+        'inquiry.reusable-persona-deleted',
+        'inquiry-template-version.created',
+        'inquiry-template-version.updated',
+        'inquiry-template-version.deleted',
+        'inquiry-template-version.published',
+      ]),
+      payload: z.object({
+        data: inquirySchema,
+        included: z.array(
+          z.union([
+            inquirySchema,
+            accountSchema,
+            inquiryTemplateSchema,
+            inquiryTemplateVersionSchema,
+            verificationDataSchema,
+            genericIncludedItemSchema,
+            userSchema,
+          ]),
+        ),
+      }),
+      'created-at': z.string().datetime(),
+    }),
+  }),
+});
+
+export type PersonaWebhookEvent = z.infer<typeof PersonaWebhookEvent>;
+
+// Root schema
+const PersonsGovernmentIdVerification = z.object({
+  data: verificationDataSchema.optional(),
+});
+
+export type PersonsGovernmentIdVerification = z.infer<
+  typeof PersonsGovernmentIdVerification
+>;

package/src/common/types/zip.type.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { validateCanadaZipCode, validateUSZipCode } from './contract-helpers';
+import { CountryCode, CountryEnumSchema } from './countries.types';
+
+export function refineAddressZip(
+  country: string | undefined | null,
+  zip: string | undefined | null,
+) {
+  return country === CountryCode['US']
+    ? !zip || validateUSZipCode(zip)
+    : country === CountryCode['CA']
+      ? !zip || validateCanadaZipCode(zip) // it's optional, so if nullish, it's valid
+      : z.string().min(2).max(10).nullable().optional().safeParse(zip).success;
+}
+
+export const ZipSchema = z.string();
+
+export const CountryZipSchema = z
+  .object({
+    country: CountryEnumSchema.nullable().optional(),
+    zip: ZipSchema.nullable().optional(),
+  })
+  .refine(({ zip, country }) => refineAddressZip(country, zip), {
+    message:
+      'zip value is not valid, it shall follow the US(12345 or 12345-6789), CANADA(A1A 1A1) format! it shall be a string for other states',
+  });
+
+export const RequiredCountryZipSchema = z
+  .object({
+    country: CountryEnumSchema,
+    zip: ZipSchema,
+  })
+  .refine(({ zip, country }) => refineAddressZip(country, zip), {
+    message:
+      'zip value is not valid, it shall follow the US(12345 or 12345-6789), CANADA(A1A 1A1) format! it shall be a string for other states',
+  });

package/src/contracts/clients/accounts/index.ts

@@ -0,0 +1,61 @@
+import { initContract } from '@ts-rest/core';
+import {
+  ForbiddenError,
+  IPaginatedAccount,
+  NotFoundError,
+  PaginationOptionsZod,
+  UnauthorizedError,
+  AccountFiltersZod,
+  AccountsIncludeQuery,
+  AccountZod,
+  accountIdSchema,
+  InternalError,
+} from '../../../common/types';
+import { z } from 'zod';
+
+const c = initContract();
+
+export const accountsContract = c.router(
+  {
+    getAccount: {
+      summary: 'Get account by id',
+      method: 'GET',
+      path: '/:id',
+      metadata: {
+        auth: true,
+      },
+      query: z.object({}).merge(AccountsIncludeQuery),
+      pathParams: z.object({
+        id: accountIdSchema,
+      }),
+      responses: {
+        200: AccountZod,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        500: InternalError,
+      },
+    },
+    getAccounts: {
+      summary: 'Get accounts',
+      method: 'GET',
+      path: '',
+      metadata: {
+        auth: true,
+      },
+      query:
+        PaginationOptionsZod.merge(AccountFiltersZod).merge(
+          AccountsIncludeQuery,
+        ),
+      responses: {
+        200: IPaginatedAccount,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        500: InternalError,
+      },
+    },
+  },
+  {
+    pathPrefix: 'accounts',
+  },
+);