Battle Texas TypeScript SDK

A small, opinionated TypeScript SDK for talking to the battle-texas-server API.

• Framework-agnostic: written in plain TS, works with SvelteKit, React, Node, etc.
• Strongly typed: types generated from the OpenAPI spec.
• Opinionated errors: success returns typed models, failures throw a single ApiError type.

This repo is intended primarily for internal use by Battle Texas apps.

Table of contents

• Requirements
• Installation
• Initialization
  • Imports
  • Setup
• Clients
• Sessions
• Locations
• Email & SMS Verifications
• Error Handling

Requirements

• TypeScript ES2020
• Supports runtimes with fetch
  • Browser
  • Node 18+
  • Node with fetch polyfill

Installation

While this is an internal package, it is public for review and comment.

With published package

npm install @battle-texas/sdk

Via private local path

Clone package to local drive, then install with:

npm install ../path_to/battle-texas-sdk

Initialization

Imports

import {
  HttpCore,
  type ClientOptions,
  LocationsClient,
  SessionsClient,
  VerificationsClient,
  ApiError
} from "@battle-texas/sdk";

Setup

const opts: ClientOptions = {
	baseUrl: "https://api.your-domain.com",
	timeoutMs: 2000,
	getAccessToken: () => sessionStorage.getItem("access_token") ?? undefined
};

const core = new HttpCore(opts);

Clients

Each client scope exposes the available endpoints for a resource type Road map:

• [x] sessions
• [x] locations (in progress)
• [x] verifications (in progress)
• [ ] business accounts
• [ ] bookings
• [ ] quotes

const locations = new LocationsClient(core);
const sessions = new SessionsClient(core);
const verifications = new VerificationsClient(core);

Sessions

Road map:

• [x] create session login
• [x] delete session logout

Begin Session

Imports

import type { CreateSessionBody } from "@battle-texas/sdk/generated/map";

Body

const body: CreateSessionBody = {
	username: "[email protected]",
	password: "correct-horse-battery-staple"
};

Usage

await sessions.create(body); // AccessToken | throws ApiError

End session

Usage

await sessions.delete(); // void | throws ApiError

Locations

Road map:

• [x] List nearest locations by zipcode
• [x] Public location by id
• [x] Private location by id
• [ ] List private locations by business id (coming soon)
• [ ] Create new location
• [ ] Update location
• [ ] Delete location

List nearest locations by zipcode

const params = { nearestZipcode: "valid zipcode" };
await locations.listNearestByZipcode(params); // PublicLocation[] | throws ApiError

Get public location by id

const id: number = 0;
await locations.publicById(id); // PublicLocation | throws ApiError

Get private location by id

const id: number = 0;
await locations.privateById(id); // PrivateLocation | throws ApiError

Email & SMS Verifications

Road map:

• [x] Email
• [ ] SMS

Request a verification email

Imports

import type { EmailVerificationPost } from "@battle-texas/sdk/generated/map";

Body

const body: EmailVerificationPost = { email: "[email protected]" };

Usage

await verifications.createEmailVerification(body); // void | throws ApiError

Verify email

Required params: uuid:string,id:number

Usage

await verifications.patchEmailVerification(uuid, id); // void | throws ApiError

Error Handling

Imports

import { ApiError } from "@battle-texas/sdk/error";

Pattern

try {
	const response = await object.method(dataBody);
} catch (err) {
  	if (err instanceof ApiError) {
  		console.error("HTTP:", err.httpStatus);
  		console.error("API code:", err.apiCode);
  		console.error("API reason:", err.apiReason);
  		console.error("Message:", err.message);
		console.error("Error Kind:", err.errorKind);
  	} else {
  		console.error("Unexpected error:", err);
  	}
}