@dalmore/api-contracts 0.0.0-dev.ab1033d → 0.0.0-dev.ada6a86

package/common/types/webhook.types.js

@@ -0,0 +1,658 @@
+import { z } from 'zod';
+import { PersonaStatus } from './common.types.js';
+/**
+ * Hook0 Webhook Provider Types
+ *
+ * Types for interacting with Hook0's webhooks-as-a-service API.
+ * @see https://documentation.hook0.com/api - API Reference
+ */
+/**
+ * Hook0 API error response format.
+ * @see https://documentation.hook0.com/api
+ */
+export const Hook0ApiErrorSchema = z.object({
+    type: z.string(),
+    status: z.number(),
+    title: z.string(),
+    detail: z.string(),
+    validation: z.unknown().nullable(),
+    id: z.string(),
+});
+/**
+ * Error returned from Hook0 provider operations.
+ * Wraps Hook0 API errors with additional context.
+ */
+export const Hook0ProviderErrorSchema = z.object({
+    message: z.string(),
+    statusCode: z.number().optional(),
+    code: z.string().optional(),
+    apiError: Hook0ApiErrorSchema.optional(),
+});
+/**
+ * Hook0 subscription target configuration.
+ * Defines where and how webhooks are delivered.
+ * @see https://documentation.hook0.com/reference/subscriptionscreate
+ */
+export const Hook0SubscriptionTargetSchema = z.object({
+    type: z.literal('http'),
+    method: z.string(),
+    url: z.string().url(),
+    headers: z.record(z.string()).optional(),
+});
+/**
+ * Hook0 subscription response from create/get operations.
+ * @see https://documentation.hook0.com/reference/subscriptionscreate
+ * @see https://documentation.hook0.com/reference/subscriptionsget
+ */
+export const Hook0SubscriptionResponseSchema = z.object({
+    subscription_id: z.string().uuid(),
+    application_id: z.string().uuid(),
+    created_at: z.string().datetime().optional(),
+    dedicated_workers: z.array(z.string()).optional(),
+    description: z.string().optional(),
+    event_types: z.array(z.string()).optional(),
+    is_enabled: z.boolean().optional(),
+    label_key: z.string().optional(),
+    label_value: z.string().optional(),
+    labels: z.record(z.string()).optional(),
+    metadata: z.record(z.string()).optional(),
+    secret: z.string(),
+    target: Hook0SubscriptionTargetSchema.optional(),
+});
+/**
+ * Simplified subscription result returned to callers.
+ */
+export const WebhookSubscriptionSchema = z.object({
+    subscriptionId: z.string(),
+    secret: z.string(),
+});
+/**
+ * Hook0 event type response from create operation.
+ * @see https://documentation.hook0.com/reference/eventtypescreate
+ */
+export const Hook0EventTypeResponseSchema = z.object({
+    service_name: z.string(),
+    resource_type_name: z.string(),
+    verb_name: z.string(),
+    event_type_name: z.string(),
+});
+/**
+ * Hook0 event type list item.
+ * @see https://documentation.hook0.com/reference/eventtypeslist
+ */
+export const Hook0EventTypeSchema = z.object({
+    name: z.string(),
+    service: z.string().optional(),
+    resource_type: z.string().optional(),
+    verb: z.string().optional(),
+});
+/**
+ * Hook0 event ingestion response.
+ * @see https://documentation.hook0.com/api/#tag/events-ingestion/POST/api/v1/event/
+ */
+export const Hook0EventResponseSchema = z.object({
+    event_id: z.string().uuid().optional(),
+    received_at: z.string().datetime().optional(),
+});
+/**
+ * Simplified event response returned to callers.
+ */
+export const WebhookEventResponseSchema = z.object({
+    eventId: z.string(),
+    receivedAt: z.string(),
+});
+/**
+ * Payload sent when ingesting events to Hook0.
+ * Contains activity data to be delivered to webhook subscribers.
+ */
+export const WebhookEventPayloadSchema = z.object({
+    activityId: z.string(),
+    activityType: z.string(),
+    accountId: z.string(),
+    targetId: z.string().nullable(),
+    targetTable: z.string().nullable(),
+    message: z.string(),
+    metadata: z.record(z.unknown()),
+    occurredAt: z.string(),
+});
+export const WebhookReceived = z.object({
+    received: z.boolean(),
+});
+// 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(),
+});
+/**
+ * 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(),
+    }),
+});
+/**
+ * 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();
+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();
+// 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();
+// 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 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(),
+        }),
+    }),
+});
+// Root schema
+const PersonsGovernmentIdVerification = z.object({
+    data: verificationDataSchema.optional(),
+});
+//# sourceMappingURL=webhook.types.js.map