@mediaviz/sdk 0.1.0

package/email_tokens.js

@@ -0,0 +1,64 @@
+import { handleResponse } from './errors.js';
+
+function stripUndef(o) { const r = {}; for (const k in o) if (o[k] !== undefined) r[k] = o[k]; return r; }
+
+export class EmailTokens {
+  constructor(ctx) { this._ctx = ctx; }
+
+  async requestEmailVerification({ email } = {}) {
+    let path = `/api/v1/request-email-verification`;
+    const query = new URLSearchParams();
+    if (email !== undefined) (Array.isArray(email) ? email : [email]).forEach(v => query.append('email', v));
+    const qs = query.toString();
+    if (qs) path += '?' + qs;
+    const resp = await fetch(this._ctx.baseUrl + path, { method: 'POST' });
+    return handleResponse(resp);
+  }
+
+  async verifyEmail(token) {
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/verify-email/${encodeURIComponent(token)}`, { method: 'POST' });
+    return handleResponse(resp);
+  }
+
+  async requestPasswordReset({ email } = {}) {
+    let path = `/api/v1/request-password-reset`;
+    const query = new URLSearchParams();
+    if (email !== undefined) (Array.isArray(email) ? email : [email]).forEach(v => query.append('email', v));
+    const qs = query.toString();
+    if (qs) path += '?' + qs;
+    const resp = await fetch(this._ctx.baseUrl + path, { method: 'POST' });
+    return handleResponse(resp);
+  }
+
+  async validateToken(token) {
+    const body = stripUndef({
+      token: token,
+    });
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/validate-token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return handleResponse(resp);
+  }
+
+  async resetPassword(token, newPassword) {
+    const body = stripUndef({
+      token: token,
+      new_password: newPassword,
+    });
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/reset-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return handleResponse(resp);
+  }
+
+  async deleteUserEmailTokens(userId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/admin/email_tokens/by_user/${encodeURIComponent(userId)}`;
+    const { data } = await this._ctx.client.request(path, 'DELETE', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+}

package/errors.js

@@ -0,0 +1,81 @@
+// Auto-generated — do not edit
+
+export class ApiError extends Error {
+  constructor(message, status, requestId, body) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.requestId = requestId;
+    this.body = body;
+  }
+}
+
+export class ValidationError extends ApiError {
+  constructor(body, status, requestId) {
+    const detail = body.detail ?? [];
+    const message = Array.isArray(detail)
+      ? detail.map(d => `${d.loc.join('.')}: ${d.msg}`).join('; ')
+      : String(detail);
+    super(message, status, requestId, body);
+    this.name = 'ValidationError';
+    this.fieldErrors = Array.isArray(detail)
+      ? detail.map(d => ({ loc: d.loc, msg: d.msg, type: d.type }))
+      : [];
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(body, status, requestId) {
+    super(body.detail ?? 'Resource not found', status, requestId, body);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class RateLimitError extends ApiError {
+  constructor(body, status, requestId, headers) {
+    super(body.detail ?? 'Rate limited', status, requestId, body);
+    this.name = 'RateLimitError';
+    this.retryAfter = parseInt(headers.get('retry-after') ?? '', 10) || null;
+  }
+}
+
+export class ServerError extends ApiError {
+  constructor(body, status, requestId) {
+    super(body.detail ?? 'Internal server error', status, requestId, body);
+    this.name = 'ServerError';
+  }
+}
+
+export async function handleResponse(response) {
+  const requestId = response.headers.get('x-request-id');
+
+  if (response.ok) {
+    return response.status === 204 ? null : response.json();
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    body = { detail: response.statusText };
+  }
+
+  switch (response.status) {
+    case 422:
+      throw new ValidationError(body, response.status, requestId);
+    case 404:
+      throw new NotFoundError(body, response.status, requestId);
+    case 429:
+      throw new RateLimitError(body, response.status, requestId, response.headers);
+    default:
+      if (response.status >= 500) {
+        throw new ServerError(body, response.status, requestId);
+      }
+      throw new ApiError(
+        body.detail ?? 'Unknown error',
+        response.status,
+        requestId,
+        body
+      );
+  }
+}

package/health.js

@@ -0,0 +1,20 @@
+import { handleResponse } from './errors.js';
+
+export class Health {
+  constructor(ctx) { this._ctx = ctx; }
+
+  async healthCheck() {
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/health/`, { method: 'GET' });
+    return handleResponse(resp);
+  }
+
+  async livenessCheck() {
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/health/live/`, { method: 'GET' });
+    return handleResponse(resp);
+  }
+
+  async readinessCheck() {
+    const resp = await fetch(this._ctx.baseUrl + `/api/v1/health/ready`, { method: 'GET' });
+    return handleResponse(resp);
+  }
+}

package/index.js

@@ -0,0 +1,21 @@
+export { MediaViz } from './MediaViz.js';
+export * from './errors.js';
+export * from './_oauth.js';
+export * from './admin.js';
+export * from './ai_model_credits.js';
+export * from './company.js';
+export * from './curated_albums.js';
+export * from './custom_albums.js';
+export * from './email_tokens.js';
+export * from './health.js';
+export * from './keywords.js';
+export * from './oauth_authorization.js';
+export * from './oauth_clients.js';
+export * from './oauth_login.js';
+export * from './oauth_token.js';
+export * from './person.js';
+export * from './photos.js';
+export * from './photoupload.js';
+export * from './projects.js';
+export * from './search.js';
+export * from './users.js';

package/keywords.js

@@ -0,0 +1,123 @@
+function stripUndef(o) { const r = {}; for (const k in o) if (o[k] !== undefined) r[k] = o[k]; return r; }
+
+export class Keywords {
+  constructor(ctx) { this._ctx = ctx; }
+
+  async createKeywordFilteringList(name, projectList = undefined) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/`;
+    const body = stripUndef({
+      name: name,
+      project_list: projectList,
+    });
+    const { data } = await this._ctx.client.request(path, 'POST', this._ctx.accessToken, this._ctx.refreshToken, body);
+    return data;
+  }
+
+  async getUserKeywordFilteringLists() {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/user`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async getKeywordFilteringListAndProjectsById(keywordListId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/${encodeURIComponent(keywordListId)}`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async getKeywordFilteringListById(keywordListId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/list/${encodeURIComponent(keywordListId)}`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async getExistingKeywordFilteringListByProject(projectTableName) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/project/${encodeURIComponent(projectTableName)}`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async getDefaultKeywordFilteringListByProject(projectTableName) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/project/${encodeURIComponent(projectTableName)}/default`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async updateKeywordFilteringListLabels(keywordListId, listKeywordsToInclude, listKeywordsToExclude) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/${encodeURIComponent(keywordListId)}`;
+    const body = stripUndef({
+      list_keywords_to_include: listKeywordsToInclude,
+      list_keywords_to_exclude: listKeywordsToExclude,
+    });
+    const { data } = await this._ctx.client.request(path, 'PUT', this._ctx.accessToken, this._ctx.refreshToken, body);
+    return data;
+  }
+
+  async updateKeywordFilteringListDetails(keywordListId, { name, projectList } = {}) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/details/${encodeURIComponent(keywordListId)}`;
+    const body = stripUndef({
+      name: name,
+      project_list: projectList,
+    });
+    const { data } = await this._ctx.client.request(path, 'PUT', this._ctx.accessToken, this._ctx.refreshToken, body);
+    return data;
+  }
+
+  async addProjectsToKeywordFilteringList(keywordListId, { projectIds } = {}) {
+    this._ctx.requireTokens();
+    let path = `/api/v1/keyword/${encodeURIComponent(keywordListId)}/projects`;
+    const query = new URLSearchParams();
+    if (projectIds !== undefined) (Array.isArray(projectIds) ? projectIds : [projectIds]).forEach(v => query.append('project_ids', v));
+    const qs = query.toString();
+    if (qs) path += '?' + qs;
+    const { data } = await this._ctx.client.request(path, 'POST', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async requestKeywordListExport(keywordListId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/export/${encodeURIComponent(keywordListId)}`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async requestKeywordListExportStatus(keywordListId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/export_status/${encodeURIComponent(keywordListId)}`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async getKeywordsAndIds() {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/all_keywords/id/label`;
+    const { data } = await this._ctx.client.request(path, 'GET', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async removeProjectsFromKeywordFilteringList(keywordListId, { projectIds } = {}) {
+    this._ctx.requireTokens();
+    let path = `/api/v1/keyword/${encodeURIComponent(keywordListId)}/projects`;
+    const query = new URLSearchParams();
+    if (projectIds !== undefined) (Array.isArray(projectIds) ? projectIds : [projectIds]).forEach(v => query.append('project_ids', v));
+    const qs = query.toString();
+    if (qs) path += '?' + qs;
+    const { data } = await this._ctx.client.request(path, 'DELETE', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+
+  async deleteKeywordFilteringListById(keywordListId) {
+    this._ctx.requireTokens();
+    const path = `/api/v1/keyword/${encodeURIComponent(keywordListId)}`;
+    const { data } = await this._ctx.client.request(path, 'DELETE', this._ctx.accessToken, this._ctx.refreshToken);
+    return data;
+  }
+}

package/oauth/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "semi": true,
+  "printWidth": 100
+}

package/oauth/README.md

@@ -0,0 +1,76 @@
+# @yourorg/oauth-sdk
+
+JavaScript SDK for the OAuth 2.0 Authorization Server. Implements Authorization Code + PKCE flow, token refresh, token revocation, and JWT payload decoding for confidential (server-side) clients.
+
+## Installation
+
+```sh
+npm install @yourorg/oauth-sdk
+```
+
+## Quick start
+
+```js
+const { OAuthClient } = require('@yourorg/oauth-sdk');
+
+const oauthClient = new OAuthClient({
+  baseUrl: 'https://api.example.com',
+  clientId: process.env.OAUTH_CLIENT_ID,
+  clientSecret: process.env.OAUTH_CLIENT_SECRET,
+  redirectUri: 'https://myapp.com/callback',
+});
+
+// Step 1: initiate login
+app.get('/login', (req, res) => {
+  const { url, state, code_verifier } = oauthClient.generateAuthorizationUrl();
+  req.session.oauthState = state;
+  req.session.codeVerifier = code_verifier;
+  res.redirect(url);
+});
+
+// Step 2: handle callback
+app.get('/callback', async (req, res) => {
+  const { code, state } = req.query;
+  if (state !== req.session.oauthState) throw new Error('State mismatch');
+
+  const tokens = await oauthClient.exchangeCode(code, req.session.codeVerifier);
+  const payload = oauthClient.decodeAccessToken(tokens.access_token);
+
+  req.session.userId = payload.user_id;
+  req.session.accessToken = tokens.access_token;
+  req.session.refreshToken = tokens.refresh_token;
+  res.redirect('/dashboard');
+});
+
+// Step 3: make authenticated requests
+app.get('/dashboard', async (req, res) => {
+  const { data, updated_tokens } = await oauthClient.request(
+    'https://api.example.com/me',
+    'GET',
+    req.session.accessToken,
+    req.session.refreshToken,
+  );
+
+  if (updated_tokens) {
+    req.session.accessToken = updated_tokens.access_token;
+    req.session.refreshToken = updated_tokens.refresh_token;
+  }
+
+  res.json(data);
+});
+```
+
+> **Important:** `generateAuthorizationUrl()` returns `{ url, state, code_verifier }`. You **must** persist `state` and `code_verifier` (e.g. in an encrypted server-side session or short-lived encrypted cookie) and pass `code_verifier` back to `exchangeCode()` in the callback handler. The SDK does not store any state between calls.
+
+## Method reference
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `generateAuthorizationUrl(state?)` | Generates PKCE verifier + challenge, builds `/oauth/authorize` URL | `AuthorizationUrlResult` |
+| `exchangeCode(code, codeVerifier, redirectUri?)` | Exchanges authorization code for tokens | `Promise<TokenResponse>` |
+| `refreshAccessToken(refreshToken)` | Issues new tokens using a refresh token | `Promise<TokenResponse>` |
+| `revokeToken(token, tokenTypeHint?)` | Revokes an access or refresh token (RFC 7009) | `Promise<void>` |
+| `decodeAccessToken(accessToken)` | Decodes JWT payload without signature verification | `TokenPayload` |
+| `request(url, method, accessToken, refreshToken, body?)` | Authenticated request with automatic 401 retry | `Promise<AuthenticatedResponse>` |
+
+See [spec.md](../../spec.md) for full API documentation.

package/oauth/browser-smoke-test.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>OAuth SDK Browser Smoke Test</title>
+</head>
+<body>
+  <pre id="output"></pre>
+  <script src="dist/oauth-sdk.umd.js"></script>
+  <script>
+    (async () => {
+      const log = (msg) => {
+        document.getElementById('output').textContent += msg + '\n';
+        console.log(msg);
+      };
+
+      try {
+        const { OAuthClient } = OAuthSDK;
+        const client = new OAuthClient({
+          baseUrl: 'https://example.com',
+          clientId: 'test-client-id',
+          clientSecret: 'test-client-secret',
+          redirectUri: 'https://example.com/callback',
+        });
+
+        const result = await client.generateAuthorizationUrl();
+
+        if (!result.url.includes('response_type=code')) {
+          throw new Error(`url missing response_type=code: ${result.url}`);
+        }
+        if (result.code_verifier.length !== 64) {
+          throw new Error(`code_verifier length ${result.code_verifier.length} !== 64`);
+        }
+        if (result.state.length !== 32) {
+          throw new Error(`state length ${result.state.length} !== 32`);
+        }
+
+        log('PASS');
+      } catch (err) {
+        log('FAIL: ' + err.message);
+      }
+    })();
+  </script>
+</body>
+</html>

package/oauth/implementation_plan.json

@@ -0,0 +1,106 @@
+[
+  {
+    "id": 1,
+    "description": "Replace Node.js crypto with Web Crypto API in pkce.js. generateCodeVerifier: use globalThis.crypto.getRandomValues(new Uint8Array(48)) + manual base64url encode + slice to 64 chars. generateCodeChallenge: use globalThis.crypto.subtle.digest('SHA-256', TextEncoder) — must become async, returns Promise<string>. generateState: use getRandomValues(new Uint8Array(16)) + hex join. Remove require('crypto'). Keep module.exports unchanged.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/src/pkce.js",
+        "location": "generateCodeVerifier",
+        "status": "replace crypto.randomBytes with getRandomValues + base64url encode"
+      },
+      {
+        "file": "sdk/javascript/src/pkce.js",
+        "location": "generateCodeChallenge",
+        "status": "make async, replace createHash with crypto.subtle.digest"
+      },
+      {
+        "file": "sdk/javascript/src/pkce.js",
+        "location": "generateState",
+        "status": "replace crypto.randomBytes with getRandomValues + hex join"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 2,
+    "description": "Update client.js to await the now-async generateCodeChallenge. In generateAuthorizationUrl, change the call to: const challenge = await generateCodeChallenge(verifier). The method is already async so the public signature is unchanged.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/src/client.js",
+        "location": "generateAuthorizationUrl",
+        "status": "add await before generateCodeChallenge call"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 3,
+    "description": "Update pkce.test.js for async generateCodeChallenge. Change the PKCE test vector assertion to use await: expect(await generateCodeChallenge(verifier)).toBe('E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'). Mark the test function async. All other tests are sync and unchanged.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/src/__tests__/pkce.test.js",
+        "location": "test('generateCodeChallenge')",
+        "status": "add async/await to test vector assertion"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 4,
+    "description": "Add Rollup build tooling. Install dev dependencies: rollup, @rollup/plugin-node-resolve, @rollup/plugin-terser. Create rollup.config.js at sdk/javascript/ with two outputs: (1) dist/oauth-sdk.umd.js — format: 'umd', name: 'OAuthSDK', exports: 'named', plugins: [terser()]; (2) dist/oauth-sdk.esm.js — format: 'esm'. Input: src/index.js. Use nodeResolve plugin to handle any internal references.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/package.json",
+        "location": "devDependencies",
+        "status": "add rollup, @rollup/plugin-node-resolve, @rollup/plugin-terser"
+      },
+      {
+        "file": "sdk/javascript/rollup.config.js",
+        "location": "module",
+        "status": "create with umd + esm output config"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 5,
+    "description": "Update package.json fields. Add: 'module': 'dist/oauth-sdk.esm.js'; 'browser': 'dist/oauth-sdk.umd.js'; 'files': ['src/', 'dist/']; scripts 'build': 'rollup -c' and 'prepublishOnly': 'npm run build'. Keep 'main': 'src/index.js' for Node.js CJS path.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/package.json",
+        "location": "root",
+        "status": "add module, browser, files fields and build scripts"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 6,
+    "description": "Add dist/ to .gitignore in sdk/javascript/. Update smoke-test.js: add await to generateAuthorizationUrl call (wrap in async IIFE or top-level await if package is ESM). Verify node smoke-test.js still exits 0.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/.gitignore",
+        "location": "root",
+        "status": "add dist/"
+      },
+      {
+        "file": "sdk/javascript/smoke-test.js",
+        "location": "main assertion block",
+        "status": "confirm generateAuthorizationUrl is awaited (should already be)"
+      }
+    ],
+    "completion_status": true
+  },
+  {
+    "id": 7,
+    "description": "Build verification. Run npm install then npm run build in sdk/javascript/. Confirm dist/oauth-sdk.umd.js and dist/oauth-sdk.esm.js are produced. Run npm test — all tests must pass. Run node smoke-test.js — must exit 0. Create sdk/javascript/browser-smoke-test.html: minimal HTML page that loads dist/oauth-sdk.umd.js via <script>, calls OAuthSDK.OAuthClient with dummy config, calls generateAuthorizationUrl(), asserts url contains 'response_type=code', logs PASS/FAIL to console.",
+    "touch_points": [
+      {
+        "file": "sdk/javascript/browser-smoke-test.html",
+        "location": "script block",
+        "status": "create browser smoke test for UMD bundle"
+      }
+    ],
+    "completion_status": true
+  }
+]