@digiteers/uloba3-sdk

TypeScript SDK for Uloba3 API - Auto-generert fra OpenAPI spesifikasjon og publisert til npm.

🎯 Formål

Dette SDK-et gir type-safe tilgang til Uloba3 API. SDK-et genereres automatisk fra API-ets OpenAPI spesifikasjon og publiseres som en privat npm-pakke.

📦 Installasjon

# I uloba3-web eller andre prosjekter
pnpm add @digiteers/uloba3-sdk@latest

# Eller spesifiser versjon
pnpm add @digiteers/[email protected]

🚀 Kom i gang

Forutsetninger

• Node.js 18+
• npm (for publisering)
• Tilgang til uloba3-backend (for å generere types)

Oppsett for utvikling

# Klon repository
cd /Users/digiteers/GitHub/uloba3/uloba3-sdk

# Installer dependencies
npm install

# Generer SDK fra lokal API (må kjøre på localhost:3001)
npm run generate

# Bygg SDK
npm run build

🔄 Utviklingsworkflow

1. Oppdatere SDK når API endres

# 1. Start API lokalt
cd ../uloba3-backend
pnpm dev:api  # Kjører på localhost:3001

# 2. Generer nye typer fra API
cd ../uloba3-sdk
npm run generate    # Henter OpenAPI spec og genererer types.ts

# 3. Bygg SDK
npm run build

# 4. Bump versjon og publiser
npm version patch   # 1.3.8 -> 1.3.9 (eller minor/major)
npm publish        # Publiserer til npm (automation token i .npmrc)

# 5. Oppdater i uloba3-web
cd ../uloba3-web
pnpm add @digiteers/uloba3-sdk@latest

2. Workflow-diagram

Backend endring
    ↓
Start lokal API (localhost:3001)
    ↓
npm run generate (i SDK)
    ↓
npm run build
    ↓
npm version patch
    ↓
npm publish
    ↓
pnpm add @digiteers/uloba3-sdk@latest (i web)
    ↓
Test i web

📝 Scripts

| Script | Beskrivelse | Når brukes | |--------|-------------|------------| | npm run generate | Generer fra lokal API (localhost:3001) | Etter API endringer | | npm run sjekk | Quick test av type generation | For debugging | | npm run generate:remote | Generer fra remote API | For produksjon sync | | npm run build | Kompiler TypeScript til JavaScript | Før publisering | | npm run pack | Lag .tgz pakke (for testing) | For lokal testing | | npm run clean | Slett dist og .tgz filer | For opprydding | | npm run typecheck | Sjekk TypeScript typer | Før commit | | npm run lint | Sjekk kode kvalitet | Før commit | | npm run format | Formater kode | Før commit |

💻 Bruk i kode

// Import SDK
import { ApiClient } from '@digiteers/uloba3-sdk';

// Initialiser klient
const client = new ApiClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001',
  token: 'auth-token-here',
  onTokenRefresh: async () => {
    // Håndter token refresh
    return 'new-token';
  }
});

// Bruk typed API metoder
const jobs = await client.jobs.getAll();
const application = await client.applications.create({
  job_id: 'job-123',
  message: 'Søknadstekst'
});

🔐 Publisering til npm

SDK bruker npm automation token for å publisere uten 2FA ved hver gang.

Oppsett (allerede gjort)

1. Automation token er konfigurert i .npmrc
2. .npmrc er gitignored for sikkerhet
3. Publisering krever ingen OTP-kode

Publisere ny versjon

npm version patch   # eller minor/major
npm publish        # Publiserer automatisk til npm

📚 API Moduler

SDK gir typed tilgang til følgende API moduler:

| Modul | Beskrivelse | |-------|-------------| | accounts | Kontohåndtering | | auth | Autentisering | | users | Brukerhåndtering | | jobs | Jobbannonser | | assistants | Assistenthåndtering | | applications | Jobbsøknader | | inquiries | Henvendelser | | contracts | Kontrakter | | contractCases | Kontraktsaker | | tasks | Oppgaver | | billing | Fakturering | | analytics | Statistikk | | documents | Dokumenter | | messaging | Meldinger | | admin | Admin funksjoner |

🏗️ Vedlikehold

Oppdater dependencies

npm update
npm audit fix

Versjonering

npm version patch  # 1.0.0 -> 1.0.1 (bugfixes)
npm version minor  # 1.0.0 -> 1.1.0 (nye features)
npm version major  # 1.0.0 -> 2.0.0 (breaking changes)

🔧 Feilsøking

Problem: TypeScript feil etter generering

# Sjekk at API kjører
curl http://localhost:3001/api/docs/json

# Regenerer med clean build
npm run clean
npm run generate
npm run build

Problem: Kan ikke publisere til npm

# Sjekk at du er logget inn
npm whoami

# Sjekk at .npmrc eksisterer med automation token
cat .npmrc

Problem: uloba3-web får ikke oppdatert SDK

# I uloba3-web
pnpm add @digiteers/uloba3-sdk@latest

# Eller spesifiser eksakt versjon
pnpm add @digiteers/[email protected]

🔐 Sikkerhet

• SDK inneholder INGEN hemmeligheter eller tokens
• All autentisering håndteres av konsumenten (web-app)
• .npmrc med automation token er gitignored
• Generert kode skal ALDRI committes med sensitive data

🤝 Bidra

1. Gjør endringer i API (uloba3-backend)
2. Generer nytt SDK med npm run generate
3. Test lokalt
4. Commit med beskrivende melding
5. Publiser med npm version patch && npm publish
6. Oppdater i uloba3-web med pnpm add @digiteers/uloba3-sdk@latest

📄 Lisens

MIT - Privat npm package under @digiteers scope.