Span App

This is a typescript SDK designed to more easily interact with Span's customer facing APIs. This package can be used both in backend context (node), and in frontend context running directly in the browser.

Usage

Installation

npm install span-app-js

Initialization

There are two ways of using span-app-js.
One is to directly import global spanApp object to use everywhere. This is a single instance that can be initialized once and then imported anywhere to be used:

import { spanApp } from "span-app-js";

spanApp.init({
  events: { apiKey: "your-events-api-key" },
});

Alternatively, a factory method can be used to instantiate new app objects and potentially keep different copies of it:

import { makeSpanApp } from "span-app-js";

const mySpanApp = await makeSpanApp({
  events: { apiKey: "your-events-api-key" },
});

Events tracking

The events tracking capabilities (under spanApp.events) are a set of features used to track arbitrary events relevant to customer operations in Span.

Common events attributes

All events accept a set of optional attributes:

• person: the person related to the event (if any). Can be determined by providing their email;
• timestamp: the point in time where the event occurred (if not provided Span will default its value to the time in which the events is received). Timestamps in the future will be rejected.
• insertId: unique ID for the event used as idempotency key to prevent double writes of the same events.

Tool usage events

To track events of tool being used, you can use the captureToolUsageEvent method.
This events require informing the id of the tool being used. These IDs can be any string that represents the tool being used. Some known tools are included in the enum SpanToolUsageKnownTool (exposed in this package) for convenience, but we will still track usage of any provided value of toolId

spanApp.events.captureToolUsageEvent({
  properties: {
    toolId: SpanToolUsageKnownTool.OrbStack,
  },
  person: {
    email: "[email protected]",
  },
  // Optionally include other general event optional attributes
});

spanApp.events.captureToolUsageEvent({
  properties: {
    toolId: "some-random-tool",
  },
  person: {
    email: "[email protected]",
  },
  // Optionally include other general event optional attributes
});

Error handling

Generally all Span app's methods that interact with our APIs are provide async (default) and async signatures. The sync variants of the methods can safely be called without blocking the main execution thread while the request is sent. This methods will fail silently and call the logger's error method to log the information of the errors. In the case of the async variants, the error object will be returned in the method's response, and can be used for bespoke handling of errors. The returned errors will be of type SpanAppError (exposed by this package).

For example:

// Default usage: non-blocking
spanApp.events.captureToolUsageEvent({...});

// Blocking
const res = await spanApp.events.captureToolUsageEventAsync({...});
if (!res.success) {
  myCustomSpanAppErrorsHandler(res.error);
}

Logging

Custom logger can be provided to span app, which will mostly be used to log errors. In order to provide logging capabilities, logger object can be fed to the spanApp object at initialization or later on using the setLogger method.

// at init
spanApp.init({
  // ... other init attributes
  logger: customLogger,
});

// or later
spanApp.setLogger(customLogger);

The provided logger object has to implement the following interface:

interface BaseLogger {
  debug: (message: string, ...args: any[]) => void;
  log: (message: string, ...args: any[]) => void;
  warn: (message: string, ...args: any[]) => void;
  error: (message: string, ...args: any[]) => void;
}

If the provided logger does not implement all methods, only the provided methods will be overridden, and the reminding methods will use the default implementation.
The default logger implementation will just log to the corresponding console.xxxx methods for each method.
In practice, even though the signature specified ...any[], only strings and JSON serializable objects will be used as logger arguments.