LitePush
SDKPackage

Types

Shared request/response type definitions exported by @litepush/sdk.

BroadcastTarget

type

Broadcast audience selector passed to send().

{ type: "all" } | { type: "user"; external_id: string } | { type: "group"; group_id: string }

NotificationPayload

interface

The notification a broadcast renders in the browser.

PropertyTypeDescription
titlestring

Title — visible to the user. 1–256 chars.

bodystring

Body text. 1–2048 chars.

icon?string

Small icon. Either an HTTPS URL (used as-is) or a base64 data:image/* URL (≤ 256 KB) the API hosts for you. Must be square (1:1). Available on every plan. Falls back to the project's default icon when omitted.

image?string

Large banner image shown below the body on supported platforms. Same formats as icon (≤ 1 MB). Hobby plan and above only.

url?string

URL opened on click. Defaults to / when omitted.

SubscribeOptions

interface
PropertyTypeDescription
userId?string

Your own user ID — lets you target this user across devices in send() ({ type: "user", external_id }). May only contain letters, numbers, underscores, and hyphens (≤ 256 chars); subscribe() throws otherwise.

SubscribeResult

interface
PropertyTypeDescription
idstring

LitePush-assigned subscriber ID (sub_*).

Urgency

type

Web Push delivery priority hint (RFC 8030 Urgency header). The push service uses it to trade off battery vs. promptness:

  • very-low — deliver only when the device is plugged in and on Wi-Fi.
  • low — deliver when the device is active.
  • normal — the default.
  • high — wake the device promptly even when it's idle (e.g. a call, a code).
"very-low" | "low" | "normal" | "high"

CreateBroadcastParams

interface
PropertyTypeDescription
targetBroadcastTarget—
notificationNotificationPayload—
ttl?number

How long (seconds) the push service keeps trying to deliver while the device is offline. 0 = deliver only if the device is connected right now. Defaults to 24 hours. Max 4 weeks (2,419,200). Available on every plan.

urgency?Urgency

Delivery priority hint. Defaults to normal. Available on every plan.

topic?string

Collapse key (≤ 32 URL-safe chars: A–Z a–z 0–9 _ -). A newer push with the same topic *replaces* an older, still-undelivered one in the gateway queue — so an offline device wakes to only the latest. Available on every plan.

scheduled_at?number

Unix-ms timestamp to schedule the broadcast for a future time instead of sending now. Plus plan and above. Must be in the future, within 90 days.

CreateBroadcastResult

interface
PropertyTypeDescription
broadcast_idstring—
scheduled_at?number

Present only when the broadcast was scheduled.

Broadcast

interface

A broadcast as returned by broadcasts.get() / broadcasts.list().

PropertyTypeDescription
idstring

Broadcast id (bdc_*).

status"pending" | "sending" | "sent" | "failed" | "canceled"

Lifecycle: pending (queued) → sending (fanning out) → sent (done) or failed. canceled for a scheduled broadcast cancelled before it fired.

source"dashboard" | "api"

Where it originated: the dashboard or the API.

targetBroadcastTarget

The audience it was sent to.

notification{ title: string; body: string; icon: string | null; image: string | null; url: string | null }

The notification content. icon/image/url are null when unset.

ttlnumber | null

Delivery options as sent. null = the default was used.

urgencyUrgency | null—
topicstring | null—
delivered_countnumber

Pushes accepted by the push gateway.

failed_countnumber

Pushes that failed (dead subscription, gateway error, retries exhausted).

scheduled_atnumber | null

Scheduled fire time (Unix ms), or null for an immediate send.

started_atnumber | null

When fan-out began (Unix ms), or null if it hasn't started.

finished_atnumber | null

When fan-out finished (Unix ms), or null if not done.

created_atnumber

When the broadcast was created (Unix ms).

ListBroadcastsParams

interface
PropertyTypeDescription
limit?number

Max rows to return. 1–100. Defaults to 20.

offset?number

Rows to skip, for paging. Defaults to 0.

ListBroadcastsResult

interface
PropertyTypeDescription
broadcastsBroadcast[]

This page of broadcasts, most recent first.

totalnumber

Total broadcasts in the project (ignores limit/offset).

limitnumber

Echoes the effective limit / offset applied.

offsetnumber—

MeResult

interface
PropertyTypeDescription
project{ id: string; name: string; domain: string; vapid_public: string }—

Group

interface
PropertyTypeDescription
idstring—
namestring—
descriptionstring | null—
member_countnumber—
created_atnumber—

ListGroupsResult

interface
PropertyTypeDescription
groupsGroup[]—

CreateGroupParams

interface
PropertyTypeDescription
namestring—
description?string—

CreateGroupResult

interface
PropertyTypeDescription
idstring—

UpdateGroupParams

interface
PropertyTypeDescription
name?string—
description?string | null

Pass null to clear the description.

AddSubscribersResult

interface
PropertyTypeDescription
addednumber

Count actually inserted — members already in the group don't double-count.

DeleteResult

interface
PropertyTypeDescription
deletednumber

Number of subscriber rows removed (0 if nothing matched).

OkResult

interface
PropertyTypeDescription
oktrue—

LitePushErrorCode

type

Stable, machine-readable error identifiers the LitePush API returns in the error.code field (see LitePushApiError). Branch on these rather than on the human-readable message. New codes may be added over time, so keep a default branch when switching exhaustively.

Auth & project resolution:

  • missing_api_key (401) — no Authorization: Bearer … header.
  • invalid_api_key (401) — the API key is unknown or revoked.
  • missing_project (400) — subscribe() reached the API with no project id.
  • project_not_found (404) — the project id doesn't exist.
  • origin_not_allowed (403) — subscribe() called from an origin that isn't

the project's registered domain.

  • project_locked (403) — the project exceeds the owner's plan limit; it's

read-only and won't accept subscribers until they upgrade or free a slot.

  • orphan_project (500) — the project's owner record is missing.

Plan limits / upgrades:

  • subscriber_limit_reached (403) — at the plan's subscriber cap.
  • monthly_push_limit_reached (403) — at the plan's monthly push cap.
  • group_limit_reached (403) — at the plan's group cap.
  • image_requires_upgrade (403) — banner images need Hobby or above.
  • scheduling_requires_upgrade (403) — scheduled sends need Plus or above.

Request validation:

  • invalid_icon / invalid_image (400) — bad icon/image data or dimensions.
  • invalid_scheduled_at (400) — schedule time missing, in the past, or too far out.

Resource state:

  • group_not_found (404), broadcast_not_found (404).
  • group_name_taken (409) — a group with that name already exists.
  • not_cancelable (409) — the broadcast already fired or isn't a scheduled one.

Transport:

  • rate_limited (429) — too many requests; see the Retry-After header.
  • internal_error (500) — an unexpected server error.
"missing_api_key" | "invalid_api_key" | "missing_project" | "project_not_found" | "origin_not_allowed" | "project_locked" | "orphan_project" | "subscriber_limit_reached" | "monthly_push_limit_reached" | "group_limit_reached" | "image_requires_upgrade" | "scheduling_requires_upgrade" | "invalid_icon" | "invalid_image" | "invalid_scheduled_at" | "group_not_found" | "broadcast_not_found" | "group_name_taken" | "not_cancelable" | "rate_limited" | "internal_error"

ApiErrorBody

interface

Shape of the API error envelope: { error: { code, message } }.

PropertyTypeDescription
error{ code: LitePushErrorCode | string & object; message: string }—

Server client

API reference for @litepush/sdk/server — the typed REST client (LitePush).