# V1 compatibility

# Naming

V2 supports two different kinds of “keep the old thing working.” This page covers both, in human terms. The exact contract is in v1-compatibility.md.

# The big picture

flowchart LR
  subgraph callers [Callers]
    OldHTTP["Legacy HTTP clients"]
    OldFacade["Old notification.success API"]
    NewClient["New NotificationsClient"]
  end

  subgraph service [This service]
    V1["/api/Notification/*"]
    V2["/v2/*"]
    DB[(Same notifications table)]
  end

  OldHTTP --> V1
  OldFacade --> V2
  NewClient --> V2
  V1 --> DB
  V2 --> DB

A notification created via V1 appears in V2 lists and vice versa. You can migrate producers and consumers on separate schedules.

# 1. Legacy HTTP surface (/api/Notification/*)

Still fully supported (marked deprecated in OpenAPI, no removal date until traffic is gone).

# What you change in the old client

Usually just the base URL — point it at this service instead of the old host.

# Auth change (important)

V1 sometimes trusted an anonymous shared API key duplicated across projects (often with a permissive DB insert). That pattern is gone.

Create / CreatePayload need real publisher credentials:

• Cognito M2M / publisher scope or group, or
• a named Worker publisher API key (PUBLISHER_API_KEYS + X-Api-Key) — see api-keys.md

Named keys are intentional and supported. What we retired is the old VL shared secret / open-table model, not “any API key ever.”

Inbox mutations still use the caller’s user Cognito token (API keys cannot manage inboxes).

# Response shape

V1 routes keep the classic envelope (never problem+json):

{
  "value": { "id": "…" },
  "errors": [],
  "warnings": []
}

# Templates (CreatePayload)

Configure V1_PAYLOAD_TEMPLATES on the Worker (JSON map of payload-type → title/body/actionUrl). {entity} is substituted from the query string. Retries are idempotent per (user, payload-type, entity) — an upgrade over classic V1.

# 2. Legacy app façade (notification.success(...))

The old Video Library quick-start looked like:

await notification.success('Title', 'Message', '/optional-url');

V2 supports that shape without shipping a magic global:

// lib/notificationService.ts
import { NotificationsClient, createNotificationService } from '@inovus-medical/notifications';

const client = new NotificationsClient({
  baseUrl: 'https://notifications.totumcloud.com',
  getAccessToken: () => auth.getValidAccessToken(),
});

export const notification = createNotificationService(client);

Existing imports of ./lib/notificationService can keep working. Toasts stay in your app.

# Intentional small differences (HTTP V1)

None of these usually matter if clients treat ids as opaque and only read the envelope:

1. Remove is a real delete (V1 called it soft-delete but offered no restore API)
2. Notification ids are UUIDs from this service
3. CreatePayload retries no longer duplicate
4. Failures set accurate HTTP status codes and fill errors[]

Full list: v1-compatibility.md.

# Suggested migration order

1. Point legacy HTTP callers at the new base URL; verify envelopes
2. Give producers credentials: Cognito M2M or named PUBLISHER_API_KEYS (retire the old VL shared REVIEW_TOOL_API_KEY / INGEST_API_KEY pair)
3. Move producers to client.publish + dedupeKey when convenient
4. Move the bell to NotificationsClient / useNotifications
5. Swap notification.success to createNotificationService
6. Decommission the old VL table / edge function / shared VL secrets when logs show no V1 traffic

flowchart TD
  A["Base URL cutover"] --> B["Publisher credentials<br/>M2M or named API keys"]
  B --> C["New publish + dedupeKey"]
  C --> D["New inbox client / React hook"]
  D --> E["Convenience façade"]
  E --> F["Turn off legacy infra"]

# Why bother migrating at all?

You don’t have to overnight — but V2 gives you pagination, honest polling, safe retries, OpenAPI, and multi-app reuse. The compatibility layers exist so migration can be boring.

Next: Advanced usage, or the deep dive in why-v2.md.