@tapizlabs/sdk

Framework-agnostic TypeScript SDK for Tapiz frontends.

The SDK contains API clients, contracts, error handling and runtime configuration for Tapiz services. It does not depend on React, Angular, Vue, or any UI framework.

Install

npm install @tapizlabs/sdk

For local development next to tapiz-reactjs-ui:

{
  "dependencies": {
    "@tapizlabs/sdk": "file:../tapiz-sdk"
  }
}

Publish workflow

This package is ready for public npm publishing.

npm ci
npm run typecheck
npm test
npm run build
npm run pack:check
npm publish --access public

For scoped public npm packages, the package uses:

{
  "publishConfig": {
    "access": "public"
  }
}

Release version helpers:

npm run release:patch
npm run release:minor
npm run release:major

Then push the tag and publish through GitHub Releases or run npm publish --access public locally.

Local development with tapiz-reactjs-ui

For day-to-day development, tapiz-reactjs-ui can use your local SDK checkout instead of the published npm version:

cd ../tapiz-reactjs-ui
npm run sdk:use-local
npm install

Because a file:../tapiz-sdk dependency reads the built SDK output, keep this running in a second terminal while editing SDK source:

cd ../tapiz-sdk
npm run dev:watch

When you want tapiz-reactjs-ui to consume the published package again:

cd ../tapiz-reactjs-ui
npm run sdk:use-registry
npm install

Configure

// src/lib/env.ts
const raw = import.meta.env;
export const env = {
  restApiUrl: raw.VITE_TAPIZ_REST_API_URL as string,
  excelApiUrl: raw.VITE_TAPIZ_EXCEL_API_URL as string,
  pdfApiUrl: raw.VITE_TAPIZ_PDF_API_URL as string,
  prodUrl: raw.VITE_TAPIZ_PROD_URL as string | undefined,
  devEnv: raw.VITE_TAPIZ_DEV_ENV as string | undefined,
  qrExpirySeconds: raw.VITE_TAPIZ_QR_EXPIRY_SECONDS as string | undefined,
};

// src/lib/tapizSdk.ts
import { createTapizSdk } from "@tapizlabs/sdk";
import { env } from "./env";

export const tapiz = createTapizSdk({
  baseUrls: {
    restApi: env.restApiUrl,
    excelApi: env.excelApiUrl,
    pdfApi: env.pdfApiUrl,
    prodUrl: env.prodUrl,
  },
  runtime: {
    devEnv: env.devEnv,
    qrExpirySeconds: env.qrExpirySeconds,
  },
});

You can also configure once and import resource clients directly:

import { configureTapizSdk } from "@tapizlabs/sdk/config";
import { authService } from "@tapizlabs/sdk/auth";

configureTapizSdk({
  baseUrls: {
    restApi: "https://api.tapiz.rs/api",
    excelApi: "https://tapiz-excel-api.vercel.app",
    pdfApi: "https://tapiz-pdf-api.vercel.app",
  },
});

await authService.login("[email protected]", "password");

Public imports

Prefer public SDK entrypoints instead of deep file paths:

import { authService } from "@tapizlabs/sdk/auth";
import { subjectService } from "@tapizlabs/sdk/subjects";
import { scoreSheetService, excelService } from "@tapizlabs/sdk/score-sheets";
import { documentService, downloadDocumentPdf } from "@tapizlabs/sdk/documents";
import apiClient from "@tapizlabs/sdk/client";
import type { TapizSdkConfig } from "@tapizlabs/sdk/config";

Available resource entrypoints include:

@tapizlabs/sdk/activity-log
@tapizlabs/sdk/admin
@tapizlabs/sdk/analytics
@tapizlabs/sdk/attendance
@tapizlabs/sdk/audit
@tapizlabs/sdk/auth
@tapizlabs/sdk/dashboard
@tapizlabs/sdk/documents
@tapizlabs/sdk/drafts
@tapizlabs/sdk/faculty-manager
@tapizlabs/sdk/forms
@tapizlabs/sdk/grades
@tapizlabs/sdk/knowledge
@tapizlabs/sdk/license
@tapizlabs/sdk/materials
@tapizlabs/sdk/news
@tapizlabs/sdk/notifications
@tapizlabs/sdk/office-hours
@tapizlabs/sdk/plan
@tapizlabs/sdk/posts
@tapizlabs/sdk/reports
@tapizlabs/sdk/score-sheets
@tapizlabs/sdk/settings
@tapizlabs/sdk/students
@tapizlabs/sdk/subjects
@tapizlabs/sdk/todos

React example

// src/lib/tapiz.ts
import { createTapizSdk } from "@tapizlabs/sdk";
import { env } from "./env";

export const tapiz = createTapizSdk({
  baseUrls: {
    restApi: env.restApiUrl,
    excelApi: env.excelApiUrl,
    pdfApi: env.pdfApiUrl,
    prodUrl: env.prodUrl,
  },
  runtime: {
    devEnv: env.devEnv,
    qrExpirySeconds: env.qrExpirySeconds,
  },
});

import { useMutation } from "@tanstack/react-query";
import { tapiz } from "../../lib/tapiz";

export function useLogin() {
  return useMutation({
    mutationFn: ({ email, password }: { email: string; password: string }) =>
      tapiz.auth.login(email, password),
  });
}

Angular example

// app/tapiz-api.service.ts
import { Injectable } from "@angular/core";
import { from } from "rxjs";
import { createTapizSdk } from "@tapizlabs/sdk";

const tapiz = createTapizSdk({
  baseUrls: {
    restApi: "https://api.tapiz.rs/api",
    excelApi: "https://tapiz-excel-api.vercel.app",
    pdfApi: "https://tapiz-pdf-api.vercel.app",
  },
});

@Injectable({ providedIn: "root" })
export class TapizApiService {
  login(email: string, password: string) {
    return from(tapiz.auth.login(email, password));
  }

  getSubjects() {
    return from(tapiz.subjects.getAll());
  }
}

Runtime adapters

Browser adapters are provided by default. For SSR, tests, or non-browser runtimes, pass explicit adapters:

createTapizSdk({
  baseUrls: {
    restApi: "https://api.tapiz.rs/api",
    excelApi: "https://tapiz-excel-api.vercel.app",
    pdfApi: "https://tapiz-pdf-api.vercel.app",
  },
  storage: {
    getItem: (key) => memory.get(key) ?? null,
    setItem: (key, value) => memory.set(key, value),
    removeItem: (key) => memory.delete(key),
  },
  events: {
    dispatch: (eventName) => console.info("Tapiz event", eventName),
  },
  downloads: {
    downloadBlob: async (blob, filename) => {
      // SSR/test/desktop-specific file handling goes here.
    },
  },
});

Error handling

Axios errors are normalized into TapizApiError by the SDK client.

import { TapizApiError } from "@tapizlabs/sdk/errors";

try {
  await tapiz.subjects.getAll();
} catch (error) {
  if (error instanceof TapizApiError) {
    console.error(error.status, error.code, error.message, error.details);
  }
}

Development

npm install
npm run typecheck
npm test
npm run build

prepublishOnly runs typecheck and build before publishing.