@triargos/studentpass

Type-safe Effect client for the StudentPasses API.

Installation

npm install @triargos/studentpass effect @effect/platform

effect and @effect/platform are peer dependencies.

Usage

import { StudentPasses } from "@triargos/studentpass"
import { Effect, Option } from "effect"

const program = Effect.gen(function* () {
  const client = yield* StudentPasses

  const result = yield* client.generatePassToken({
    token: "my-provider-jwt",
    organization: {
      name: "Example School",
      primaryColor: "#3B82F6",
      logoUrl: "https://example.com/logo.png",
    },
    student: {
      fullName: "Max Mustermann",
      grade: "10A",
      avatarUrl: "https://example.com/avatar.png",
      accessCode: Option.none(),
      backInfo: Option.none(),
    },
    provider: "triargos",
  })

  console.log(result.token)
  console.log(result.redirectUrl)
})

Effect.runPromise(
  program.pipe(
    Effect.provide(StudentPasses.Default({ baseUrl: "https://passes.example.com" })),
  ),
)

API

StudentPasses

An Effect service. Provide via StudentPasses.Default({ baseUrl }) which includes FetchHttpClient.

generatePassToken(request)

Sends student and organization data to the API. The server validates the provider bearer token, then returns a signed pass generation token and a redirect URL.

Request fields:

| Field | Type | Description | |----------------|-------------------|----------------------------------------------------------| | token | string | Bearer token for provider auth (JWT or session token) | | organization | OrganizationData| School name, primary color (hex), logo URL | | student | StudentData | Full name, grade, avatar URL, optional access code/back info | | provider | PassProvider | "triargos" or "manual" |

Response:

| Field | Type | Description | |---------------|----------|----------------------------------------| | token | string | Signed pass generation token | | redirectUrl | string | URL to redirect user for pass download |

Errors:

| Error | Status | When | |------------------------------------|--------|-----------------------------------| | InvalidPassProviderHttpError | 400 | Unknown provider value | | PassProviderUnauthorizedHttpError| 401 | Invalid or expired bearer token | | InternalServerHttpError | 500 | Unexpected server error |

Error Handling

const result = yield* client.generatePassToken(request).pipe(
  Effect.catchTags({
    InvalidPassProviderHttpError: (e) =>
      Effect.logError(`Bad provider: ${e.provider}`),
    PassProviderUnauthorizedHttpError: (e) =>
      Effect.logError(`Auth failed: ${e.message}`),
    InternalServerHttpError: (e) =>
      Effect.logError(`Server error: ${e.message}`),
  }),
)

Re-exports

The SDK re-exports the schemas used in requests and responses for convenience:

• GeneratePassTokenPayload, GeneratePassTokenResponse
• InvalidPassProviderHttpError, PassProviderUnauthorizedHttpError, InternalServerHttpError
• OrganizationData, StudentData, PassProvider