npm package: @getuserfeedback/adapters
Description: getuserfeedback integration adapters
Latest version: 0.5.3

# `@getuserfeedback/adapters`

`@getuserfeedback/adapters` publishes external-system translation layers built on top of the public widget protocol.

## GTM

The `@getuserfeedback/adapters/gtm` entrypoint is the authoritative source for Google Tag Manager template generation. It owns:

- GTM color scheme normalization logic
- GTM template parameter generation
- GTM runtime source generation
- GTM permission generation
- GTM importable `template.tpl` file generation
- GTM template defaults, help text, and option labels
- the canonical loader script base URL pattern

### Public exports

Template inputs and init translation:

- `GTM_CONSENT_TYPES`
- `isGtmConsentType(value)`
- `normalizeGtmThemeInput(input)`
- `resolveDefaultConsentFromGtm(input)`
- `buildInitOptionsFromGtmTemplate(input)`

Types:

- `GtmConsentType`
- `GtmConsentValue`
- `GtmConsentState`
- `GtmTemplateInput`

Template generation:

- `DEFAULT_GTM_LOADER_SCRIPT_BASE_URL`
- `buildGtmTemplateParameters(options?)`
- `buildGtmRuntimeSource(options?)`
- `buildGtmPermissions(options?)`
- `buildGtmTemplateInfo(options?)`
- `buildGtmTemplateParts(options?)`
- `buildGtmTemplateArtifact(options?)`
- `buildGtmTemplateFileSource(options?)`

### Consent behavior

The GTM template no longer exposes consent settings in its UI.

- The template follows GTM Consent Mode directly.
- getuserfeedback `defaultConsent` scopes are inferred from GTM's standard consent signals only.
- `analytics.measurement` follows `analytics_storage`.
- There is no custom consent remapping UI or runtime path.
- If no GTM consent state is available, the adapter leaves `defaultConsent` unset.

### Color scheme behavior

Generated GTM color scheme support accepts:

- fixed `light`
- fixed `dark`
- fixed `system`
- host-sync via protocol auto-detect attributes
- GTM variable-driven values
- comma-separated auto-detect attribute lists

The adapter normalizes all of these into protocol-valid `colorScheme`.

### Identity behavior

The generated template supports:

- `Intelligent` mode, which reads common data-layer keys for user ID, email, phone, first name, and last name
- `Custom` mode, which lets GTM explicitly map a main identity and traits
- `Disabled` mode, which skips identify entirely

### Generate GTM output

```ts
import {
	buildGtmTemplateArtifact,
	buildGtmTemplateFileSource,
} from "@getuserfeedback/adapters/gtm";

const artifact = buildGtmTemplateArtifact({
	loaderScriptBaseUrl: "https://cdn.getuserfeedback.com/widget/loader/v1",
});

const templateFile = buildGtmTemplateFileSource({
	loaderScriptBaseUrl: "https://cdn.getuserfeedback.com/widget/loader/v1",
});
```

Use the package script to write a local importable file:

```sh
bun run generate:gtm-template
```

For the sandbox-backed GTM smoke:

```sh
bun run generate:gtm-template:sandbox-hybrid
```

`buildGtmTemplateArtifact()` returns the rendered GTM sections. `buildGtmTemplateFileSource()` returns a full importable `template.tpl`.

### Verifying GTM template changes

When edits in this package change GTM template generation or runtime behavior, the usual verification path spans more than this package:

- Regenerate the hybrid upload artifact from `packages/adapters`.
- Run `bun run test` in `packages/adapters`.
- Run the real GTM smoke e2e from `packages/widget-browser-tests`:

```sh
bun run test:playwright:substrate-sandbox -- src/tests/gtm-smoke.e2e.ts
```

That browser test lives outside this package because it exercises the uploaded GTM template against the sandbox host, local CDN/API endpoints, and a real GTM container. It typically expects `GTM_CONTAINER_ID` to be set in `packages/widget-browser-tests/.env.local`.

### What the GTM repo should still own

After importing the published package, the GTM repo should only own:

- brand thumbnail and base64 image assets
- `metadata.yaml`
- publishing and release workflow

It should not rebuild parameters, runtime source, permissions, file assembly, or GTM-specific init payload translation.

### Customizing the loader base URL

Pass `loaderScriptBaseUrl` to:

- `buildGtmRuntimeSource`
- `buildGtmPermissions`
- `buildGtmTemplateParts`
- `buildGtmTemplateArtifact`
- `buildGtmTemplateFileSource`

The same base URL is used to derive the runtime loader URL and the `inject_script` permission pattern.

Pass `runtimeEndpoints` when you need the generated template to point loader bootstrap at non-default `core` and `api` endpoints.

### Versioning expectations

Any change that affects generated GTM output is a public package change and should be versioned accordingly. This includes:

- parameter shape or defaults
- runtime behavior
- permission generation
- color scheme normalization
- identity lookup behavior
- consent derivation behavior

Release notes should call out template-affecting changes explicitly.