SDK

Integrate WeTransform directly into your JavaScript or Vue 3 application using the official SDK packages.

`@wetransform/core`

Headless browser SDK. Open WeTransform as a modal or inline widget, authenticate users, and listen to typed events — framework-agnostic.

`@wetransform/vue`

Vue 3 wrapper around @wetransform/core. Provides a renderless component and a useWeTransform() composable.

Installation

Vanilla JS / any framework

npm install @wetransform/core

📦 @wetransform/core on npm

Vue 3

npm install @wetransform/vue

@wetransform/core is a peer dependency and will be installed automatically.

📦 @wetransform/vue on npm

Configuration

Both packages share the same configuration object. Two values require setup in your WeTransform account.

Organization handle (organizationHandle): The URL slug for your branded page (e.g. your-company for your-company.send-a-file.io). Set it in Integrations → Embed — same setting as Define Embed URL.
Signature (authentication.signature): An HMAC-SHA256 token generated server-side to authenticate each user session. It uses the same secret and algorithm as the Embed signature.

Signature — server-side generation

Use your embed secret key (from Integrations → Embed) to compute an HMAC-SHA256 over a payload, then pass the result as authentication.signature. The payload is the customer ID, optionally followed by the context you want to scope the session to, joined with a colon (:) in the fixed order customerId:templateHandle:sourceId. Include only the parts you need — append more only to narrow the scope.

// Customer only — full access for that customer
Signature = HMAC_SHA256("1234", "secret_key")

// Customer + template — scoped to a single template
Signature = HMAC_SHA256("1234:template-test", "secret_key")

// Customer + template + source — scoped to a single transformation
Signature = HMAC_SHA256("1234:template-test:550e8400-e29b-41d4-a716-446655440000", "secret_key")

Never expose the secret key to the browser. Generate the signature in your backend and pass it to the frontend.

The payload must contain exactly the context you pass in the config. If you provide a templateHandle, you must sign it as part of the payload; likewise for sourceId. A signature whose payload does not match the parameters sent to the SDK will be rejected.

Configuration reference

Option	Type	Required	Description
`organizationHandle`	`string`	yes	Your organization's URL slug (e.g. `your-company`)
`authentication.customerId`	`string`	yes	Unique identifier for the current user in your system
`authentication.signature`	`string`	yes	HMAC-SHA256 signature generated server-side
`authentication.templateHandle`	`string`	no	Template handle for the current session
`authentication.sourceId`	`string`	no	Source identifier for the current session
`locale`	`'en' \| 'fr'`	no	UI language. Defaults to `'en'`
`displayAsModal`	`boolean`	no	Open as a centered modal overlay. Defaults to `true`
`initialLocation`	`string`	no	Starting page inside WeTransform. When omitted, it is inferred from the authentication context — see Initial location for all values and the inference rules
`mountElement`	`string \| HTMLElement`	no	Custom container for inline (non-modal) mounting — element ID or element reference
`customization.colors.primary`	`string`	no	Primary brand color (CSS color, e.g. `#1a73e8`). See Customization.
`customization.colors.secondary`	`string`	no	Secondary brand color (CSS color)

Initial location

initialLocation chooses which screen opens first. Each location requires a matching authentication context, and that context must be part of the signed payload (see the signature note above).

Location	What opens	Required authentication	Auto-selected when
`transformations`	The customer's list of transformations	`customerId` + `signature`	No `templateHandle` and no `sourceId`
`uploader`	File upload screen for a template	+ `templateHandle`	`templateHandle` set, `sourceId` not set
`finalize`	Final review / submit screen for a transformation	+ `templateHandle` + `sourceId`	Both `templateHandle` and `sourceId` set
`mapper`	Column mapping	+ `templateHandle` + `sourceId`	explicit only
`sourcePreview`	Read-only preview of the source file	+ `templateHandle` + `sourceId`	explicit only
`sourceUpdate`	Update an existing source	+ `templateHandle` + `sourceId`	explicit only
`loadSource`	Import a source	+ `templateHandle` + `sourceId`	explicit only
`scheduler`	Schedule a transformation	+ `templateHandle` + `sourceId`	explicit only

When initialLocation is omitted, the SDK infers only transformations, uploader, or finalize from the authentication fields you pass. Every other location must be set explicitly, and it requires the templateHandle / sourceId shown above (enforced at the TypeScript type level).

Customization

Pass a customization object to apply your brand colors to the WeTransform UI.

customization: {
  colors: {
    primary: '#1a73e8',   // main brand color
    secondary: '#34a853', // accent color
  },
}

`@wetransform/core`

Use this package directly in any JavaScript or TypeScript project.

Basic usage

import { createWeTransform } from '@wetransform/core'

const sdk = createWeTransform({
  organizationHandle: 'your-org',
  locale: 'en',
  displayAsModal: true,
  authentication: {
    customerId: 'customer_id',
    signature: signatureGeneratedServerSide,
  },
  customization: {
    colors: { primary: '#1a73e8', secondary: '#34a853' },
  },
})

// Open the WeTransform UI
sdk.open()

// Listen to events
sdk.on('successSubmit', ({ fileUrl, templateHandle, customerId, signature, userFileName }) => {
  console.log('File ready:', fileUrl)
})

// Clean up when done
sdk.destroy()

Instance methods

Method	Description
`open()`	Initializes authentication and mounts the WeTransform UI
`close()`	Closes the UI and unmounts the iframe
`destroy()`	Closes and tears down all SDK resources
`setLocale(locale)`	Switches the UI language (`'en'` or `'fr'`) at runtime
`on(event, handler)`	Subscribes to an SDK event. Returns an unsubscribe function

`@wetransform/vue`

Two integration styles are available. Choose the one that fits your component structure.

1. Renderless component

Drop <WeTransformSdk> into your template. Use v-model:open to control visibility and listen to events with @successSubmit / @error.

Component usage

<script setup>
import { ref } from 'vue'
import { WeTransformSdk } from '@wetransform/vue'

const isOpen = ref(false)
const locale = ref('en')

const config = {
  organizationHandle: 'your-org',
  authentication: {
    customerId: 'customer_id',
    signature: signatureGeneratedServerSide,
  },
}

function onSuccess({ fileUrl, templateHandle, userFileName }) {
  console.log('File ready:', fileUrl)
}
</script>

<template>
  <button @click="isOpen = true">Open WeTransform</button>

  <WeTransformSdk
    v-model:open="isOpen"
    :config="config"
    :locale="locale"
    @successSubmit="onSuccess"
    @error="console.error"
  />
</template>

Do not pass mountElement or locale in the config when using the component — pass locale as a prop (it is reactive) and mounting is managed internally. For other structural config changes, remount using Vue's :key attribute.

2. Composable

Use useWeTransform() for more granular control. Accepts reactive config via a getter function — re-initializes automatically when config changes.

Composable usage

import { useWeTransform } from '@wetransform/vue'

const { open, close, destroy, setLocale, isOpen, weTransformInstance, on } = useWeTransform(() => ({
  organizationHandle: 'your-org',
  authentication: {
    customerId: customerId.value,
    signature: signature.value,
  },
}))

// Subscribe to events directly via the composable
on('successSubmit', ({ fileUrl }) => {
  console.log('File ready:', fileUrl)
})

Events

The SDK emits the following events. Subscribe with sdk.on(event, handler) in @wetransform/core, or via component event bindings in @wetransform/vue.

Event	Description	Payload
`open`	Fired when the UI opens	—
`close`	Fired when the UI closes	—
`ready`	Fired when the iframe has fully loaded	—
`successSubmit`	Fired when a file has been processed successfully	`{ customerId, templateHandle, fileUrl, signature, userFileName }`
`error`	Fired when an error occurs	`{ code, message, stack? }`
`destroy`	Fired when the SDK instance is destroyed	—

Verify successSubmit: The signature in the payload is signed by WeTransform. Always verify it server-side before processing the file — use the same HMAC-SHA256 check as the Embed inbound verification.

SDK

@wetransform/core

@wetransform/vue

Installation

Vanilla JS / any framework

Vue 3

Configuration

Signature — server-side generation

Configuration reference

Initial location

Customization

@wetransform/core

Basic usage

Instance methods

@wetransform/vue

1. Renderless component

Component usage

2. Composable

Composable usage

Events

Ready to go?

`@wetransform/core`

`@wetransform/vue`

`@wetransform/core`

`@wetransform/vue`