@dylibso/xtp v0.0.0-rc1

@dylibso/xtp

The JS SDK for XTP.

import createClient from '@dylibso/xtp'

const client = await createClient({
  appId: 'app_xxxxxxxxxxxxxxxxxxxxxxxx',
  token: 'xtp0_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  useWasi: true
})

/*
Assuming you have an extension point named "myGreatExtensionPoint" with
a schema like:

  ---
  version: v0
  exports:
    - exportName
*/
const result = await client.extensionPoints.myGreatExtensionPoint.exportName(
  'guest tag',
  'input',
  'default value' // can be an object, Uint8Array, or string
)

console.log(result)

API

fn createClient(opts: XTPClientOptions): Promise<Client>

Create a client with the provided options. On instantiation, the Client fetches the available list of extension points from the XTP API. If this call fails the promise returned by createClient will reject.

interface XTPClientOptions

• baseUrl: defaults to https://xtp.dylibso.com.
• token: An XTP API Token.
• functions: A {[string]: {[string]: CallableFunction}} map to be exposed to modules.
• logger: A pino-compatible logger.
• keepResidentMs: The number of milliseconds to keep plugins "live" after a call. This means the plugin is in-memory and subsequent calls to the same extension point and guest tag will re-use the plugin instance. Resets after each call. Defaults to environment variable XTP_KEEP_RESIDENT_MS, or 5000ms.
• refetchAfterMs: The number of milliseconds to treat local cached plugin data as "fresh"; after which the client will "re-fetch" the installed plugin for the given extension point and tag to revalidate the cache.
• useWasi: boolean, defaults to true -- whether or not to enable WASIp1 for guests.
• storage: Any ExtensionStorage interface. Uses localStorage on Deno, cacache on Node.
• fetch: Any fetch-compatible function for making requests.

class Client

fn client.clone(opts: Partial<XTPClientOptions>): Client

Clone an existing client, bypassing the "load extension points" call during typical startup. Options for the client can be partially overridden.

fn close(): Promise<void>

Close all "live" plugins. May be called repeatedly.

fn inviteGuest(opts: RegisterGuest): Promise<Json>

Invite a guest to develop and install plugins on your XTP application.

interface RegisterGuest

• email: string: The guest's email address.
• name: string: The human-readable name of the guest.
• guestKey: string: A unique string held by your application to identify the guest.

prop extensionPoints

fn extensionPoints[extName: string][exportName: string](guestKey: string, param: T, defaultValue:T): Promise<T>

const result = await client.extensionPoints.foo.bar('my guest key', {hello: 'world'}, {})

Call a plugin export installed by a guest (identified by guestKey) at an extension point.

Returns defaultValue if the plugin could not be called. defaultValue is returned in cases of cache corruption, network connectivity issues, or if the guest doesn't have a plugin installed at that extension point.

interface ExtensionStorage

Implement your own extension storage for fun and profit! Reach for this interface if the default storage options aren't working for you -- if you'd like to store plugins in a database, for example.

fn getByExtIdGuestKey(extId: string, guestKey: string): Promise<StoredPlugin | null>

Fetch plugin content based on an extId/guestKey pair. Must refer to the same StoredPlugin content as returned by getByETag.

Return null if not present.

fn getByETag(etag: string): Promise<StoredPlugin | null>

Fetch plugin content based on the ETag value returned by fetching installations. Must refer to the same StoredPlugin content as returned by getByExtIdGuestKey.

Return null if not present.

fn store(extId: string, guestKey: string, etag: string, meta: Record<string, string>, content: Uint8Array): Promise<void>

Store plugin content, indexed by both (extId, guestKey) and etag.

interface StoredPlugin

• metadata: Record<string, string>: Metadata about the record. Should include etag, content-type, and last (a number representing the milliseconds since unix epoch at which the plugin content was last stored.)
• data: Uint8Array: The plugin content, suitable for passing to WebAssembly.compile.
• size: number: The size of the stored data.