Utilities

import {
  waitForSelector, waitForSelectorRemoval, querySelectorAll, getTextContent, getMetaContent, observeDOM,
  fetchFromPage, fetchJSON, postJSON, postForm, postFormData, putJSON, patchJSON, deleteJSON,
  fetchText, buildQueryString, httpStatusToToolError, parseRetryAfterMs, parseRateLimitHeader, stripUndefined,
  getLocalStorage, setLocalStorage, removeLocalStorage,
  getSessionStorage, setSessionStorage, removeSessionStorage,
  getCookie,
  getAuthCache, setAuthCache, clearAuthCache, findLocalStorageEntry,
  getPageGlobal, getCurrentUrl, getPageTitle,
  retry, sleep, waitUntil,
  log,
} from '@opentabs-dev/plugin-sdk';

function waitForSelector<T extends Element = Element>(selector: string, opts?: WaitForSelectorOptions): Promise<T>;

// Wait for the dashboard to load before interacting
const dashboard = await waitForSelector('.dashboard-loaded');
 
// Short timeout for elements that should appear quickly
const header = await waitForSelector('#app-header', { timeout: 3000 });

function waitForSelectorRemoval(selector: string, opts?: WaitForSelectorOptions): Promise<void>;

// Wait for a loading spinner to disappear
await waitForSelectorRemoval('.loading-spinner');
 
// Then interact with the loaded content
const items = querySelectorAll('.list-item');

function querySelectorAll<T extends Element = Element>(selector: string): T[];

// Returns a real array — use .map(), .filter(), .find() directly
const rows = querySelectorAll<HTMLTableRowElement>('table tbody tr');
const names = rows.map(row => row.cells[0]?.textContent?.trim() ?? '');

function getTextContent(selector: string): string | null;

const username = getTextContent('.profile-name');
const count = getTextContent('.notification-badge');

function getMetaContent(name: string): string | null;

// Read CSRF tokens or app configuration from <meta> tags
const csrfToken = getMetaContent('csrf-token');
const apiBase = getMetaContent('api-base-url');

function observeDOM(
  selector: string,
  callback: (mutations: MutationRecord[], observer: MutationObserver) => void,
  options?: ObserveDOMOptions,
): () => void;

// Watch for new messages in a chat container
const cleanup = observeDOM('#message-list', (mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node instanceof HTMLElement && node.classList.contains('message')) {
        // Handle new message
      }
    }
  }
});
 
// Later: disconnect the observer
cleanup();

function fetchFromPage(url: string, init?: FetchFromPageOptions): Promise<Response>;

// GET request with page cookies
const response = await fetchFromPage('/api/users');
const users = await response.json();
 
// POST with custom timeout
const response = await fetchFromPage('/api/export', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ format: 'csv' }),
  timeout: 60_000,
});

// Unchecked cast (backward compatible)
function fetchJSON<T>(url: string, init?: FetchFromPageOptions): Promise<T | undefined>;
 
// Zod schema validation — validates the parsed JSON and returns the typed result
function fetchJSON<T extends z.ZodType>(
  url: string, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

// Simple usage with type cast
interface Channel { id: string; name: string }
const channels = await fetchJSON<Channel[]>('/api/channels');
 
// Type-safe usage with Zod schema validation
import { z } from 'zod';
const channelSchema = z.object({ id: z.string(), name: z.string() });
const channels = await fetchJSON('/api/channels', undefined, z.array(channelSchema));
// channels is typed as { id: string; name: string }[] — validated at runtime

// Unchecked cast (backward compatible)
function postJSON<T>(url: string, body: unknown, init?: FetchFromPageOptions): Promise<T | undefined>;
 
// Zod schema validation — validates the parsed JSON and returns the typed result
function postJSON<T extends z.ZodType>(
  url: string, body: unknown, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

const result = await postJSON<{ ok: boolean }>('/api/messages', {
  channel: 'general',
  text: 'Hello from OpenTabs!',
});
 
// With Zod schema validation
import { z } from 'zod';
const responseSchema = z.object({ ok: z.boolean(), ts: z.string() });
const result = await postJSON('/api/messages', { channel: 'general', text: 'Hi!' }, undefined, responseSchema);
// result is typed as { ok: boolean; ts: string } — validated at runtime

// Unchecked cast (backward compatible)
function postForm<T>(url: string, body: Record<string, string>, init?: FetchFromPageOptions): Promise<T | undefined>;
 
// Zod schema validation — validates the parsed JSON and returns the typed result
function postForm<T extends z.ZodType>(
  url: string, body: Record<string, string>, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

// Submit a URL-encoded form
const result = await postForm<{ ok: boolean }>('/api/auth/token', {
  grant_type: 'authorization_code',
  code: authCode,
  redirect_uri: 'https://example.com/callback',
});

// Unchecked cast (backward compatible)
function postFormData<T>(url: string, body: FormData, init?: FetchFromPageOptions): Promise<T | undefined>;
 
// Zod schema validation — validates the parsed JSON and returns the typed result
function postFormData<T extends z.ZodType>(
  url: string, body: FormData, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

// Upload a file via multipart form data
const formData = new FormData();
formData.append('file', fileBlob, 'report.csv');
formData.append('channels', 'C12345');
 
const result = await postFormData<{ ok: boolean; file: { id: string } }>('/api/files.upload', formData);

function putJSON<T>(url: string, body: unknown, init?: FetchFromPageOptions): Promise<T | undefined>;
function putJSON<T extends z.ZodType>(
  url: string, body: unknown, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

const updated = await putJSON<{ ok: boolean }>('/api/users/123', {
  name: 'New Name',
  role: 'admin',
});

function patchJSON<T>(url: string, body: unknown, init?: FetchFromPageOptions): Promise<T | undefined>;
function patchJSON<T extends z.ZodType>(
  url: string, body: unknown, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

const patched = await patchJSON<{ ok: boolean }>('/api/users/123', {
  status: 'active',
});

function deleteJSON<T>(url: string, init?: FetchFromPageOptions): Promise<T | undefined>;
function deleteJSON<T extends z.ZodType>(
  url: string, init: FetchFromPageOptions | undefined, schema: T,
): Promise<z.infer<T>>;

const result = await deleteJSON<{ ok: boolean }>('/api/users/123');
// result may be undefined for 204 No Content responses

function fetchText(url: string, init?: FetchFromPageOptions): Promise<string>;

// Fetch raw text content — diffs, logs, plain-text API responses
const diff = await fetchText('/api/pull-requests/42/diff');
 
// Fetch a job log with a custom timeout
const log = await fetchText('/api/jobs/123/log', { timeout: 60_000 });

function stripUndefined<T extends Record<string, unknown>>(obj: T): Partial<T>;

// Build a request body with optional fields — no manual if-undefined checks needed
const { task_id, ...updates } = params;
await postJSON(`/api/tasks/${task_id}`, stripUndefined(updates));
 
// Only undefined is removed — null, 0, false, and "" are preserved
stripUndefined({ a: 1, b: undefined, c: null, d: 0, e: false, f: '' });
// → { a: 1, c: null, d: 0, e: false, f: '' }

function buildQueryString(
  params: Record<string, string | number | boolean | (string | number | boolean)[] | undefined>,
): string;

// Build a query string for an API call
const qs = buildQueryString({
  channel: 'C12345',
  limit: 50,
  include_all_metadata: true,
  cursor: undefined, // omitted from the output
});
// → "channel=C12345&limit=50&include_all_metadata=true"
 
const messages = await fetchJSON<Message[]>(`/api/messages?${qs}`);
 
// Array values append multiple entries for the same key
const qs2 = buildQueryString({ types: ['public_channel', 'private_channel'] });
// → "types=public_channel&types=private_channel"

function httpStatusToToolError(response: Response, message: string): ToolError;

const response = await fetch('/api/data', { credentials: 'include' });
if (!response.ok) {
  throw httpStatusToToolError(response, `Failed to fetch data: HTTP ${response.status}`);
}

function parseRetryAfterMs(value: string): number | undefined;

const retryAfter = response.headers.get('Retry-After');
if (retryAfter) {
  const ms = parseRetryAfterMs(retryAfter);
  if (ms) await sleep(ms);
}

function parseRateLimitHeader(headers: Headers): number | undefined;

// Handle rate limiting from any API — checks all common header formats
const response = await fetchFromPage('/api/data');
if (response.status === 429) {
  const retryMs = parseRateLimitHeader(response.headers);
  if (retryMs) throw ToolError.rateLimited('Rate limited', retryMs);
  throw ToolError.rateLimited('Rate limited');
}

function getLocalStorage(key: string): string | null;

function setLocalStorage(key: string, value: string): void;

function removeLocalStorage(key: string): void;

function getSessionStorage(key: string): string | null;

function setSessionStorage(key: string, value: string): void;

function removeSessionStorage(key: string): void;

function getCookie(name: string): string | null;

// Check for an auth token stored in different locations
const token =
  getLocalStorage('auth_token') ??
  getSessionStorage('auth_token') ??
  getCookie('auth_token');

function getAuthCache<T>(namespace: string): T | null;

// Retrieve a cached API token
const token = getAuthCache<string>('slack-api-token');
 
// Retrieve a complex cached auth object
interface AuthData { token: string; expiresAt: number }
const auth = getAuthCache<AuthData>('my-plugin-auth');

function setAuthCache<T>(namespace: string, value: T): void;

// Cache an extracted API token for reuse across tool invocations
const token = getPageGlobal('TS.boot_data.api_token') as string | undefined;
if (token) {
  setAuthCache('slack-api-token', token);
}

function clearAuthCache(namespace: string): void;

// Clear a cached token when it's known to be expired
clearAuthCache('slack-api-token');

function findLocalStorageEntry(
  predicate: (key: string) => boolean,
): { key: string; value: string } | null;

// Find a localStorage entry with a dynamic key prefix
const entry = findLocalStorageEntry((key) => key.startsWith('auth_token_'));
if (entry) {
  const token = JSON.parse(entry.value);
}
 
// Find a key matching a pattern
const session = findLocalStorageEntry((key) => key.includes('session'));

function getPageGlobal(path: string): unknown;

// Access deeply nested page globals safely
const token = getPageGlobal('TS.boot_data.api_token') as string | undefined;
const userId = getPageGlobal('App.currentUser.id') as number | undefined;
const config = getPageGlobal('__APP_CONFIG__.features') as Record<string, boolean> | undefined;

function getCurrentUrl(): string;

function getPageTitle(): string;

function retry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

// Retry a flaky API call with exponential backoff
const data = await retry(
  () => fetchJSON<UserData>('/api/user/profile'),
  { maxAttempts: 5, delay: 500, backoff: true },
);
 
// Retry with cancellation
const controller = new AbortController();
const data = await retry(
  () => fetchJSON<SearchResults>('/api/search?q=test'),
  { maxAttempts: 3, signal: controller.signal },
);

function sleep(ms: number, opts?: SleepOptions): Promise<void>;

// Wait 2 seconds between operations
await doFirstThing();
await sleep(2000);
await doSecondThing();
 
// Cancel a sleep early with an AbortSignal
const controller = new AbortController();
setTimeout(() => controller.abort(), 1000);
await sleep(5000, { signal: controller.signal }); // resolves/rejects after ~1s

function waitUntil(
  predicate: () => boolean | Promise<boolean>,
  opts?: WaitUntilOptions,
): Promise<void>;

// Wait for a page global to be set
await waitUntil(() => getPageGlobal('App.ready') === true);
 
// Wait for an element to have specific content
await waitUntil(
  () => getTextContent('.status-badge') === 'Connected',
  { interval: 500, timeout: 15_000 },
);
 
// Cancel polling after 5 seconds
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);
await waitUntil(
  () => getTextContent('.status') === 'Ready',
  { signal: controller.signal },
);

import { log } from '@opentabs-dev/plugin-sdk';

log.info('Fetching channels', { workspaceId: 'T12345' });
log.warn('Rate limited, retrying', { retryAfterMs: 2000 });
log.error('Failed to send message', error);
log.debug('Raw API response', { status: 200, body: responseData });