fix(sdk,api): align SDK auth types with API and fix refresh token flow

- Replace AuthTokens with AuthResponse in SDK types — add `user` field, remove
  the non-existent `expiresIn` field that the API never returns. AuthTokens is
  kept as a deprecated type alias for backward compatibility.
- Fix refreshToken() to POST the refresh token in the request body instead of
  relying on httpOnly cookies, which were inaccessible to the SDK in Node and
  cross-origin browser contexts.
- Add POST /auth/refresh endpoint that accepts the refresh token either from the
  request body (`refreshToken`) or from the `refresh_token` httpOnly cookie,
  keeping the existing Next.js proxy flow working.
- Include a refresh token in login() and register() API responses so the SDK
  has a token to send on refresh.
- Add findById() to UsersRepository for refresh-token user lookup.
- Add cookie-parser middleware to parse cookies for the cookie-based refresh path.
- Add comprehensive unit tests: AuthController.refresh, AuthService.refresh,
  SDK client auth flows (login, register, refreshToken, 401 auto-refresh).
- Update SDK README with corrected types and refresh usage examples.
- Bump both @stellar/streaming-sdk and stellar-streaming-api to v1.1.0.

Closes #527

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: Topmatrixmor2014

api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellar-streaming-api",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Stellar Streaming API built with NestJS",
   "main": "dist/main.js",
   "scripts": {
@@ -27,6 +27,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
     "compression": "^1.8.1",
+    "cookie-parser": "^1.4.7",
     "helmet": "8.1.0",
     "pg": "^8.20.0",
     "reflect-metadata": "^0.1.13",
@@ -40,6 +41,7 @@
     "@nestjs/cli": "^10.3.0",
     "@types/bcrypt": "^6.0.0",
     "@types/compression": "^1.8.1",
+    "@types/cookie-parser": "^1.4.10",
     "@types/express": "^5.0.6",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.10.0",

api/src/auth/auth.controller.spec.ts

@@ -0,0 +1,96 @@
+import { UnauthorizedException } from "@nestjs/common"
+import { AuthController } from "./auth.controller"
+import { AuthResponse, AuthService } from "./auth.service"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface MockAuthService {
+  refresh: jest.Mock<Promise<AuthResponse>>
+}
+
+function mockAuthService(): MockAuthService {
+  return {
+    refresh: jest.fn(),
+  }
+}
+
+function makeController(service: MockAuthService): AuthController {
+  return new AuthController(service as unknown as AuthService)
+}
+
+function authResponse(): AuthResponse {
+  return {
+    user: {
+      id: 1,
+      username: "testuser",
+      email: "test@example.com",
+      createdAt: new Date("2026-01-01T00:00:00Z"),
+    },
+    accessToken: "access.token",
+    refreshToken: "refresh.token",
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("AuthController", () => {
+  let service: MockAuthService
+  let controller: AuthController
+
+  beforeEach(() => {
+    service = mockAuthService()
+    controller = makeController(service)
+    jest.clearAllMocks()
+  })
+
+  describe("refresh", () => {
+    it("forwards the body refresh token to the service", async () => {
+      service.refresh.mockResolvedValue(authResponse())
+
+      const result = await controller.refresh("body.token", undefined)
+
+      expect(service.refresh).toHaveBeenCalledWith("body.token")
+      expect(result).toEqual(authResponse())
+    })
+
+    it("falls back to the refresh_token cookie when no body token is present", async () => {
+      service.refresh.mockResolvedValue(authResponse())
+
+      const result = await controller.refresh(undefined, {
+        cookies: { refresh_token: "cookie.token" },
+      })
+
+      expect(service.refresh).toHaveBeenCalledWith("cookie.token")
+      expect(result).toEqual(authResponse())
+    })
+
+    it("prefers the body token over the cookie when both are present", async () => {
+      service.refresh.mockResolvedValue(authResponse())
+
+      await controller.refresh("body.token", {
+        cookies: { refresh_token: "cookie.token" },
+      })
+
+      expect(service.refresh).toHaveBeenCalledWith("body.token")
+      expect(service.refresh).not.toHaveBeenCalledWith("cookie.token")
+    })
+
+    it("throws UnauthorizedException when neither body token nor cookie is provided", () => {
+      expect(() => controller.refresh(undefined, undefined)).toThrow(
+        UnauthorizedException,
+      )
+      expect(service.refresh).not.toHaveBeenCalled()
+    })
+
+    it("throws UnauthorizedException when the cookie is empty", () => {
+      expect(() => controller.refresh(undefined, { cookies: {} })).toThrow(
+        UnauthorizedException,
+      )
+      expect(service.refresh).not.toHaveBeenCalled()
+    })
+  })
+})

api/src/auth/auth.controller.ts

@@ -4,6 +4,8 @@ import {
   HttpCode,
   HttpStatus,
   Post,
+  Req,
+  UnauthorizedException,
 } from "@nestjs/common"
 import { ApiCreatedResponse, ApiOkResponse, ApiOperation, ApiTags } from "@nestjs/swagger"
 import { AuthResponse, AuthService } from "./auth.service"
@@ -43,4 +45,27 @@ export class AuthController {
   login(@Body() dto: LoginDto): Promise<AuthResponse> {
     return this.authService.login(dto)
   }
+
+  @Post("refresh")
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: "Refresh an expired access token",
+    description:
+      "Accepts a refresh token via the request body (`refreshToken`) or via " +
+      "the `refresh_token` httpOnly cookie. Returns a fresh access token, " +
+      "refresh token, and the user profile.",
+  })
+  @ApiOkResponse({
+    description: "Token refresh successful. New token pair returned.",
+  })
+  refresh(
+    @Body("refreshToken") bodyToken?: string,
+    @Req() req?: { cookies?: Record<string, string> },
+  ): Promise<AuthResponse> {
+    const token = bodyToken ?? req?.cookies?.refresh_token
+    if (!token) {
+      throw new UnauthorizedException("refresh token is required")
+    }
+    return this.authService.refresh(token)
+  }
 }

api/src/auth/auth.service.spec.ts

@@ -15,24 +15,28 @@ jest.mock("bcrypt", () => ({
 
 interface MockJwtService {
   sign: jest.Mock<string>
+  verify: jest.Mock<{ sub: number }>
 }
 
 interface MockUsersRepository {
   findByEmail: jest.Mock<Promise<User | null>>
   findByUsername: jest.Mock<Promise<User | null>>
+  findById: jest.Mock<Promise<User | null>>
   create: jest.Mock<Promise<User>>
 }
 
 function mockJwtService(): MockJwtService {
   return {
     sign: jest.fn(),
+    verify: jest.fn(),
   }
 }
 
 function mockUsersRepository(): MockUsersRepository {
   return {
     findByEmail: jest.fn(),
     findByUsername: jest.fn(),
+    findById: jest.fn(),
     create: jest.fn(),
   }
 }
@@ -106,6 +110,7 @@ describe("AuthService", () => {
         username: dto.username,
       })
       expect(result.accessToken).toBe("jwt.token.here")
+      expect(result.refreshToken).toBe("jwt.token.here")
       expect(result.user).toEqual({
         id: 1,
         username: dto.username,
@@ -175,6 +180,7 @@ describe("AuthService", () => {
         username: user.username,
       })
       expect(result.accessToken).toBe("jwt.token.here")
+      expect(result.refreshToken).toBe("jwt.token.here")
       expect(result.user).toEqual({
         id: user.id,
         username: user.username,
@@ -237,4 +243,73 @@ describe("AuthService", () => {
       })
     })
   })
+
+  // -- refresh -----------------------------------------------------------
+
+  describe("refresh", () => {
+    it("returns new token pair for a valid refresh token", async () => {
+      const user = dummyUser()
+      jwt.verify.mockReturnValue({ sub: user.id })
+      users.findById.mockResolvedValue(user)
+      jwt.sign.mockReturnValueOnce("new.access.token").mockReturnValueOnce("new.refresh.token")
+
+      const result = await service.refresh("valid.refresh.token")
+
+      expect(jwt.verify).toHaveBeenCalledWith("valid.refresh.token")
+      expect(users.findById).toHaveBeenCalledWith(user.id)
+      expect(result.accessToken).toBe("new.access.token")
+      expect(result.refreshToken).toBe("new.refresh.token")
+      expect(result.user).toEqual({
+        id: user.id,
+        username: user.username,
+        email: user.email,
+        createdAt: user.created_at,
+      })
+    })
+
+    it("throws UnauthorizedException when the refresh token is invalid or expired", async () => {
+      jwt.verify.mockImplementation(() => {
+        throw new Error("jwt expired")
+      })
+
+      await expect(service.refresh("expired.token")).rejects.toThrow(
+        UnauthorizedException,
+      )
+      expect(users.findById).not.toHaveBeenCalled()
+    })
+
+    it("throws UnauthorizedException when the user no longer exists", async () => {
+      jwt.verify.mockReturnValue({ sub: 999 })
+      users.findById.mockResolvedValue(null)
+
+      await expect(service.refresh("valid.for.deleted.user")).rejects.toThrow(
+        UnauthorizedException,
+      )
+      expect(jwt.sign).not.toHaveBeenCalled()
+    })
+
+    it("signs the access token with the standard short-lived payload", async () => {
+      const user = dummyUser()
+      jwt.verify.mockReturnValue({ sub: user.id })
+      users.findById.mockResolvedValue(user)
+      jwt.sign
+        .mockReturnValueOnce("access")
+        .mockReturnValueOnce("refresh")
+
+      await service.refresh("token")
+
+      // First call: access token (short-lived, full claims)
+      expect(jwt.sign).toHaveBeenNthCalledWith(1, {
+        sub: user.id,
+        email: user.email,
+        username: user.username,
+      })
+      // Second call: refresh token (long-lived, sub only)
+      expect(jwt.sign).toHaveBeenNthCalledWith(
+        2,
+        { sub: user.id },
+        { expiresIn: "7d" },
+      )
+    })
+  })
 })

api/src/auth/auth.service.ts

@@ -23,6 +23,7 @@ export interface SafeUser {
 export interface AuthResponse {
   user: SafeUser
   accessToken: string
+  refreshToken: string
 }
 
 @Injectable()
@@ -62,6 +63,7 @@ export class AuthService {
     return {
       user: toSafeUser(user),
       accessToken: this.signToken(user),
+      refreshToken: this.signRefreshToken(user),
     }
   }
 
@@ -85,6 +87,34 @@ export class AuthService {
     return {
       user: toSafeUser(user),
       accessToken: this.signToken(user),
+      refreshToken: this.signRefreshToken(user),
+    }
+  }
+
+  /**
+   * Refresh an access token using a valid refresh token.
+   *
+   * Accepts the refresh token either from the request body (SDK path) or
+   * from the httpOnly cookie (browser proxy path). Validates the token,
+   * looks up the user, and returns a fresh token pair.
+   */
+  async refresh(refreshToken: string): Promise<AuthResponse> {
+    let payload: { sub: number }
+    try {
+      payload = this.jwtService.verify<{ sub: number }>(refreshToken)
+    } catch {
+      throw new UnauthorizedException("invalid or expired refresh token")
+    }
+
+    const user = await this.usersRepository.findById(payload.sub)
+    if (!user) {
+      throw new UnauthorizedException("user not found")
+    }
+
+    return {
+      user: toSafeUser(user),
+      accessToken: this.signToken(user),
+      refreshToken: this.signRefreshToken(user),
     }
   }
 
@@ -96,6 +126,14 @@ export class AuthService {
       username: user.username,
     })
   }
+
+  /** Create a long-lived JWT refresh token for the given user. */
+  private signRefreshToken(user: User): string {
+    return this.jwtService.sign(
+      { sub: user.id },
+      { expiresIn: "7d" },
+    )
+  }
 }
 
 /** Strip the password hash from a user row before returning to clients. */

api/src/auth/users.repository.ts

@@ -27,6 +27,14 @@ export class UsersRepository {
     return rows[0] ?? null
   }
 
+  async findById(id: number): Promise<User | null> {
+    const { rows } = await this.pool.query(
+      "SELECT id, username, email, password_hash, created_at FROM users WHERE id = $1",
+      [id],
+    )
+    return rows[0] ?? null
+  }
+
   async findByUsername(username: string): Promise<User | null> {
     const { rows } = await this.pool.query(
       "SELECT id, username, email, password_hash, created_at FROM users WHERE username = $1",

api/src/main.ts

@@ -2,6 +2,7 @@ import { ValidationPipe } from "@nestjs/common"
 import { NestFactory } from "@nestjs/core"
 import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger"
 import compression from "compression"
+import cookieParser from "cookie-parser"
 import helmet from "helmet"
 import { AppModule } from "./app.module"
 import { SanitizeStringsPipe } from "./common/sanitization/sanitize-strings.pipe"
@@ -15,6 +16,9 @@ const COMPRESSION_THRESHOLD_BYTES = 1024
 async function bootstrap() {
   const app = await NestFactory.create(AppModule)
 
+  // Parse cookies for refresh-token handling.
+  app.use(cookieParser())
+
   // Issue #89: Apply Helmet middleware globally for secure HTTP headers
   app.use(
     helmet({