Skip to main content
The SW Combine SDK is written in TypeScript 5.5+ strict mode and ships its own type definitions at dist/types/index.d.ts. Every method returns a fully typed response — you rarely need to annotate types yourself, but you can import any type or enum directly when you want explicit annotations or need to reference specific values.

​
Installing and importing

The SDK supports both ESM (import) and CommonJS (require). Import the client and any types you need from the same package entry point: 
import {
  SWCombine,
  AccessType,
  MessageMode,
  type Character,
  type CharacterMe,
  type Page,
  type SWCError,
} from 'swcombine-sdk';
All types are re-exported from swcombine-sdk. You do not need to import from dist/types/index.d.ts directly.

​
Enum reference

The SDK exports two enums that you pass as parameters to API calls.

​
MessageMode

Controls which mailbox to query when listing messages.
MemberValue
MessageMode.Received"received"
MessageMode.Sent"sent"
import { SWCombine, MessageMode } from 'swcombine-sdk';

const client = new SWCombine({ token: process.env.SWC_ACCESS_TOKEN });

// Fetch the authenticated character's received messages
const inbox = await client.character.messages.list({
  mode: MessageMode.Received,
});

// Fetch sent messages
const sent = await client.character.messages.list({
  mode: MessageMode.Sent,
});

​
AccessType

Passed in ClientConfig to choose whether the OAuth flow issues a refresh token.
MemberValueBehaviour
AccessType.Online"online"Access token only — no refresh token
AccessType.Offline"offline"Issues a refresh token for automatic renewal
import { SWCombine, AccessType } from 'swcombine-sdk';

const client = new SWCombine({
  clientId: process.env.SWC_CLIENT_ID!,
  clientSecret: process.env.SWC_CLIENT_SECRET!,
  redirectUri: 'http://localhost:3000/callback',
  accessType: AccessType.Offline, // receive a refresh token
});

​
Explicit type annotations

TypeScript infers return types automatically, but you can annotate variables when you want to make contracts explicit or pass data to other functions.

​
Single-entity responses

import { SWCombine, type CharacterMe, type FactionDetail } from 'swcombine-sdk';

const client = new SWCombine({ token: process.env.SWC_ACCESS_TOKEN });

// Type is inferred — annotation is optional but clear
const me: CharacterMe = await client.character.me();
console.log(me.name, me.xpLevel);

const faction: FactionDetail = await client.faction.get({ uid: '20:123' });
console.log(faction.name, faction.leader.value);

​
Paginated list responses

Every list() method returns Page<T>. Annotate with the specific item type if you need to pass the page to a typed function: 
import {
  SWCombine,
  type Page,
  type FactionListItem,
  type MessageListItem,
  type CreditLogEntry,
} from 'swcombine-sdk';

const client = new SWCombine({ token: process.env.SWC_ACCESS_TOKEN });

const factions: Page<FactionListItem> = await client.faction.list();
factions.data.forEach((f: FactionListItem) => console.log(f.value));

const messages: Page<MessageListItem> = await client.character.messages.list({ uid: '1:12345' });
const firstSender: string | undefined = messages.data[0]?.attributes?.uid;

const log: Page<CreditLogEntry> = await client.character.creditlog.list({ uid: '1:12345' });
log.data.forEach((entry) => console.log(entry.amount));

​
Error handling with SWCError

All API errors are thrown as SWCError instances. Import the class to narrow the type in catch blocks: 
import { SWCombine, SWCError, type CharacterMe } from 'swcombine-sdk';

const client = new SWCombine({ token: process.env.SWC_ACCESS_TOKEN });

try {
  const me: CharacterMe = await client.character.me();
  console.log(me.name);
} catch (err) {
  if (err instanceof SWCError) {
    console.error(`API error ${err.statusCode}: ${err.type}`);
    if (err.retryable) {
      console.error('This request can be retried.');
    }
  } else {
    throw err;
  }
}

​
Scope types

When building OAuth authorization URLs you pass an array of scopes. The SDK exports typed scope constants so you never mistype a scope string: 
import { SWCombine, CharacterScopes, MessageScopes, FactionScopes } from 'swcombine-sdk';

const client = new SWCombine({
  clientId: process.env.SWC_CLIENT_ID!,
  clientSecret: process.env.SWC_CLIENT_SECRET!,
  redirectUri: 'http://localhost:3000/callback',
});

const url = client.auth.getAuthorizationUrl({
  scopes: [
    CharacterScopes.READ,
    MessageScopes.READ,
    FactionScopes.READ,
  ],
  state: crypto.randomUUID(),
});
Helper functions are also available if you want predefined scope sets: 
import { getAllScopes, getReadOnlyScopes, getMinimalScopes } from 'swcombine-sdk';

// All available scopes
const all = getAllScopes();

// Read-only scopes only
const readOnly = getReadOnlyScopes();

​
Full exported type reference

The following types and interfaces are exported from swcombine-sdk: Core response types
TypeDescription
CharacterBasic character object (uid, handle, name)
CharacterMeFull authenticated character profile
FactionBasic faction object
FactionDetailFull faction detail response
FactionListItemRow returned by faction.list()
FactionMemberRow returned by faction.members.list()
MessageFull message with communication body
MessageListItemRow returned by character.messages.list()
CreditLogEntryRow returned by credit log endpoints
Galaxy types
TypeDescription
GalaxySystem / GalaxySystemListItemSystem detail / list row
GalaxyPlanet / GalaxyPlanetListItemPlanet detail / list row
GalaxySector / GalaxySectorListItemSector detail / list row
GalaxyStation / GalaxyStationListItemStation detail / list row
GalaxyCity / GalaxyCityListItemCity detail / list row
Configuration and utility types
TypeDescription
ClientConfigOptions accepted by the SWCombine constructor
OAuthTokenAccess token + optional refresh token + expiry
Page<T>Wrapper returned by all list() methods
RateLimitInfoRate limit headers parsed from API responses
SWCErrorError class for all API errors
Enums
TypeDescription
MessageModeReceived or Sent mailbox
AccessTypeOnline or Offline OAuth access