@nowly/sdk

Type definitions and helpers for Nowly presences.

Install

npm install @nowly/sdk

Zero dependencies.

Presence scripts

Presence and Assets are globals injected by the extension at runtime - no import needed.

const settings = Presence.Settings({
  "show-details": {
    type: "boolean",
    default: true,
    label: { "en-US": "Show details" },
    description: { "en-US": "Display page details on Discord" },
  },
})

const presence = new Presence(settings)

presence.on("UpdateData", (ctx) => {
  presence.setActivity({
    details: "Browsing",
    state: "Some page",
    largeImageKey: Assets.Logo,
    type: PresenceType.Watching,
  })
})

Typed localized strings

Language packs are optional. A presence that uses them can infer its string keys directly from locales/en-US.json, without generating TypeScript files:

import type enUS from "./locales/en-US.json"

const presence = new Presence()

presence.on("UpdateData", async () => {
  const locale = await presence.getStrings<typeof enUS>()

  await presence.setActivity({
    details: presence.formatString(locale.watchingVideo, { title: "My video" }),
  })
})

The type-only import is removed from the bundle. It gives editors autocomplete for every key declared in en-US.json and makes unknown keys a TypeScript error. Presences without language packs can continue using inline strings and do not need to call getStrings().

Use {name} placeholders in locale values and formatString(template, params) to inject dynamic values. Unknown placeholders are left unchanged.

Helpers

import { createMediaTimestamps, PresenceType } from "@nowly/sdk"
import type { PresenceData } from "@nowly/sdk"

createMediaTimestamps(videoElement)
// => { startTimestamp: number, endTimestamp: number } | {}

API

| Export | Kind | Description | |---|---|---| | PresenceData | type | Activity data sent to Discord | | PresenceType | const | { Playing: 0, Streaming: 1, Listening: 2, Watching: 3, Competing: 5 } | | PresenceTypeValue | type | 0 \| 1 \| 2 \| 3 \| 5 | | PresenceButton | type | { label: string, url: string } | | PresenceSetting | type | Boolean, Input, Select, or Slider setting | | InferSettings | type | Infers the settings object shape from definitions | | LocaleString | type | Partial<Record<string, string>> | | UpdateDataContext | type | Context received in UpdateData listener | | PresenceInstance | type | Runtime presence instance interface | | PresenceConstructor | type | Presence class interface | | PresenceAssets | type | { Logo, Icon, Thumbnail } | | createMediaTimestamps() | fn | Compute start/end timestamps from media elements | | createImageProxyUrl() | fn | Build direct image proxy URL | | createImageProxyPath() | fn | Build image proxy URL from parts | | createCachedImageProxyUrl() | fn | Build cached image proxy URL (async) |

Metadata (including optional discordNative) is exported from @nowly/sdk/metadata, not the main entry.

Presence instance methods

PresenceInstance (the object returned by new Presence(settings)) exposes:

| Method | Description | |---|---| | on("UpdateData", ctx => ...) | Registers the tick handler; ctx.settings holds current user settings | | setActivity(data) | Push PresenceData to Discord (async) | | clearActivity() | Clear the current activity | | getStrings<T>() | Load this presence's locales/{lang}.json content (async) | | formatString(template, params) | Interpolate {name}-style placeholders in a localized string | | getSetting<T>(key) | Read a single user setting value by key (async) | | info(message) / error(message) | Log to the extension's runtime log panel |

License

MIT