@wetransform/core

Headless browser SDK to open WeTransform in your app (modal or inline), authenticate, and interact through a typed event API.

Installation

npm install @wetransform/core

Usage

import { createWeTransform } from '@wetransform/core'

const sdk = createWeTransform({
  organizationHandle: 'acme',
  locale: 'en',
  displayAsModal: true,
  initialLocation: 'transformations',
  authentication: {
    customerId: 'ext-123',
    signature: 'signed-payload',
    templateHandle: 'demo-template',
    sourceId: 'newsletter',
  },
})

// Subscribing to the successSubmit event
sdk.on('successSubmit', (payload) => console.log('File successfully submitted', payload))

// Opening WeTransform
await sdk.open()
// Dynamically switch locale without remounting
await sdk.setLocale('fr')
// Close WeTransform
await sdk.close()
// Destroy WeTransform session
await sdk.destroy()

API

createWeTransform(config)

Returns a WeTransformInstance with:

• open(): Promise<void> - initializes auth and mounts WeTransform
• close(): Promise<void> - closes SDK UI and unmounts WeTransform
• destroy(): Promise<void> - closes and tears down SDK resources
• setLocale(locale): Promise<void> - updates locale/auth context and syncs iframe locale when active
• on(event, handler): () => void - subscribes to SDK events, returns unsubscribe function

WeTransformConfig

• organizationHandle: string
• locale?: 'en' | 'fr'
• authentication: WeTransformAuthenticationConfig
• initialLocation?: 'transformations' | 'uploader' | 'mapper' | 'finalize' | 'sourcePreview' | 'sourceUpdate' | 'scheduler'
• displayAsModal?: boolean (default: true)
• mountElement?: string | HTMLElement (default id: weTransform_iframeContainer, used when displayAsModal is false)

locale defaults to 'en' when not provided.

Runtime locale switching

• setLocale('en' | 'fr') is additive and does not require destroy/recreate.
• If the locale is unchanged, setLocale is a no-op.
• If SDK status is open, locale is sent to iframe immediately via bridge messaging.
• If SDK status is opening, locale is sent after iframe readiness is reached.
• setLocale updates auth API URL context to {VITE_SENDER_API_URL}/{locale}/send/{organizationHandle} for subsequent auth calls.
• Calling setLocale after destroy() throws Cannot set locale after destroy.

Inline mounting behavior (displayAsModal: false)

When displayAsModal is false, wetTransform SDK mounts the iframe into:

• the element with id weTransform_iframeContainer by default, or
• the element resolved from mountElement when you provide one.

If the target element does not exist, the SDK creates the container and appends it to document.body.

Some initialLocation values require additional auth fields:

• uploader: requires authentication.templateHandle
• mapper, finalize, sourcePreview, sourceUpdate, scheduler: require both authentication.templateHandle and authentication.sourceId

WeTransformAuthenticationConfig

• customerId: string
• signature: string
• templateHandle?: string
• sourceId?: string

Events

Supported sdk.on(...) events:

• open
• close
• destroy
• onReady
• successSubmit with payload

{
  customerId: string
  templateHandle: string
  fileUrl: string
  signature: string
  // Deprecated
  redirectUrl: string
}

• error with payload { code: string; message: string }