teak-sdk 0.0.0-stage → 1.0.80

package/dist/types/client/authDiscovery.d.ts

@@ -0,0 +1,18 @@
+export declare const OAUTH_SURFACES: readonly ["cli", "raycast", "chrome", "firefox", "safari"];
+export type OAuthSurface = (typeof OAUTH_SURFACES)[number];
+export interface AuthDiscovery {
+    readonly authorizationEndpoint: string;
+    readonly clients: Readonly<Record<OAuthSurface, string>>;
+    readonly issuer: string;
+    readonly primary: "betterauth" | "workos";
+    readonly resource: string;
+    readonly revocationEndpoint?: string;
+    readonly tokenEndpoint: string;
+}
+export declare const validateOAuthUrl: (raw: unknown, local?: boolean) => URL;
+export declare function discoverAuthServer(siteUrl: string, options?: {
+    fetch?: typeof fetch;
+    forceRefresh?: boolean;
+    localIssuer?: string;
+    timeoutMs?: number;
+}): Promise<AuthDiscovery>;

package/dist/types/client/sdk.d.ts

@@ -0,0 +1,193 @@
+export { type AuthDiscovery, discoverAuthServer, type OAuthSurface, validateOAuthUrl, } from "./authDiscovery.js";
+import { type CardType } from "../shared/constants.js";
+import type { FileKind, FilePreviewFacts } from "../shared/fileFormats.js";
+export type { CardType } from "../shared/constants.js";
+export declare const CARD_TYPES: readonly ["text", "link", "image", "video", "audio", "document", "palette", "quote"];
+export declare const CARD_SORTS: readonly ["newest", "oldest"];
+export declare const ERROR_CODES: readonly ["AUTH_REQUIRED", "BAD_REQUEST", "CONFIG_ERROR", "CONFLICT", "CONTENT_TOO_LARGE", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_INPUT", "INVALID_UTF8", "METHOD_NOT_ALLOWED", "NETWORK_ERROR", "NOT_FOUND", "PARSE_ERROR", "RATE_LIMITED", "REQUEST_FAILED", "TIMEOUT", "UNAUTHORIZED"];
+export type CardSort = (typeof CARD_SORTS)[number];
+export type TeakApiErrorCode = (typeof ERROR_CODES)[number];
+export type FetchLike = typeof fetch;
+export interface TokenProvider {
+    getAccessToken: () => Promise<string | null> | string | null;
+    onUnauthorized?: (rejectedToken: string) => Promise<string | null> | string | null;
+}
+export interface Card {
+    aiSummary: string | null;
+    aiTags: string[];
+    aiTranscript: string | null;
+    appUrl: string;
+    colors: Array<{
+        hex: string;
+        name?: string;
+    }>;
+    compactUrl: string | null;
+    content: string;
+    createdAt: number;
+    detailUrl: string | null;
+    fileExtension: string | null;
+    fileKind: FileKind | null;
+    fileLanguage: string | null;
+    fileName: string | null;
+    filePreview: FilePreviewFacts | null;
+    fileSize: number | null;
+    fileUrl: string | null;
+    id: string;
+    isFavorited: boolean;
+    linkAuthor: string | null;
+    linkPreviewImageUrl: string | null;
+    linkPreviewMedia: Array<{
+        type: "image" | "video";
+        url: string;
+        contentType?: string;
+        width?: number;
+        height?: number;
+        posterUrl?: string;
+        posterContentType?: string;
+        posterWidth?: number;
+        posterHeight?: number;
+    }>;
+    linkPublishedAt: string | null;
+    linkPublisher: string | null;
+    linkSiteName: string | null;
+    metadataDescription: string | null;
+    metadataTitle: string | null;
+    mimeType: string | null;
+    notes: string | null;
+    placeholderUrl: string | null;
+    screenshotUrl: string | null;
+    tags: string[];
+    thumbnailUrl: string | null;
+    type: CardType | string;
+    updatedAt: number;
+    url: string | null;
+}
+export type CardListItem = Partial<Card> & Pick<Card, "aiTags" | "appUrl" | "createdAt" | "id" | "isFavorited" | "tags" | "type" | "updatedAt">;
+export interface PageInfo {
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+export interface CardsPage {
+    items: CardListItem[];
+    pageInfo: PageInfo;
+}
+export interface CardChangesResponse {
+    deletedIds: string[];
+    items: Card[];
+    pageInfo: PageInfo;
+}
+export interface TagSummary {
+    count: number;
+    name: string;
+}
+export interface CreateCardInput {
+    cardType?: CardType;
+    content?: string;
+    fileEtag?: string;
+    fileKey?: string;
+    fileName?: string;
+    fileSize?: number;
+    mimeType?: string;
+    notes?: string | null;
+    source?: string;
+    tags?: string[];
+    url?: string;
+}
+export interface UpdateCardInput {
+    content?: string;
+    metadataTitle?: string | null;
+    notes?: string | null;
+    tags?: string[];
+    url?: string;
+}
+export interface CreateUploadInput {
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+}
+export interface CreateUploadResponse {
+    expiresIn: number;
+    fileKey: string;
+    maxFileSize: number;
+    method: "PUT";
+    uploadUrl: string;
+}
+export interface CreateCardResponse {
+    appUrl: string;
+    card?: Card;
+    cardId: string;
+    status: "created";
+}
+export interface BulkCardsResponse {
+    operation: "create" | "update" | "favorite" | "delete";
+    results: unknown[];
+    summary: {
+        failed: number;
+        succeeded: number;
+        total: number;
+    };
+}
+export declare class TeakApiError extends Error {
+    code: TeakApiErrorCode;
+    requestId?: string;
+    retryAt?: number;
+    status?: number;
+    constructor(code: TeakApiErrorCode, message?: string, init?: {
+        requestId?: string;
+        retryAt?: number;
+        status?: number;
+    });
+}
+export declare const staticTokenProvider: (token: string) => TokenProvider;
+export declare const normalizeLimit: (limit?: number) => number;
+export declare const buildCardsSearchParams: (input: {
+    createdAfter?: number;
+    createdBefore?: number;
+    cursor?: string;
+    favorited?: boolean;
+    include?: string;
+    limit?: number;
+    query?: string;
+    sort?: CardSort;
+    tag?: string;
+    type?: CardType | string | readonly (CardType | string)[];
+}) => string;
+export declare const createTeakClient: (options: {
+    baseUrl?: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    tokenProvider: TokenProvider;
+    userAgent?: string;
+}) => {
+    cards: {
+        bulk: (operation: BulkCardsResponse["operation"], items: unknown[]) => Promise<BulkCardsResponse>;
+        changes: (input: {
+            cursor?: string;
+            limit?: number;
+            since: number;
+        }) => Promise<CardChangesResponse>;
+        create: (input: CreateCardInput) => Promise<CreateCardResponse>;
+        delete: (id: string) => Promise<null>;
+        favorites: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        get: (id: string) => Promise<Card>;
+        list: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        search: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        setFavorite: (id: string, isFavorited: boolean) => Promise<Card>;
+        update: (id: string, input: UpdateCardInput) => Promise<Card>;
+    };
+    tags: {
+        list: () => Promise<{
+            items: TagSummary[];
+        }>;
+    };
+    uploads: {
+        create: (input: CreateUploadInput) => Promise<CreateUploadResponse>;
+        putFile: (uploadUrl: string, bytes: BodyInit, mimeType: string) => Promise<{
+            fileEtag: string | undefined;
+        }>;
+    };
+};
+export type TeakClient = ReturnType<typeof createTeakClient>;
+export declare const parseTags: (value: string | undefined) => string[] | undefined;
+export declare const isCardType: (value: string) => value is CardType;
+export declare const isStringList: (value: unknown) => value is string[];

package/dist/types/devUrls.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_TEAK_DEV_APP_URL = "http://localhost:3000";
+export declare const DEFAULT_TEAK_DEV_CONVEX_SITE_URL = "https://reminiscent-kangaroo-59.convex.site";
+export declare const DEFAULT_TEAK_DEV_API_URL = "https://reminiscent-kangaroo-59.convex.site";
+export declare const DEFAULT_TEAK_DEV_DOCS_URL = "http://localhost:3001";
+export interface DevUrlEnv {
+    TEAK_DEV_API_URL?: unknown;
+    TEAK_DEV_APP_URL?: unknown;
+    TEAK_DEV_DOCS_URL?: unknown;
+    [key: string]: unknown;
+}
+export declare const resolveTeakDevAppUrl: (env?: DevUrlEnv) => string;
+export declare const resolveTeakDevApiUrl: (env?: DevUrlEnv) => string;
+export declare const resolveTeakDevDocsUrl: (env?: DevUrlEnv) => string;
+export declare const isLocalDevelopmentHostname: (hostname: string) => boolean;
+export declare const isLocalDevelopmentUrl: (value: string) => boolean;

package/dist/types/shared/boundedResponse.d.ts

@@ -0,0 +1,2 @@
+export declare const readResponseBlobWithinLimit: (response: Response, maxBytes: number) => Promise<Blob | null>;
+export declare const readResponseTextWithinLimit: (response: Response, maxBytes: number) => Promise<string | null>;

package/dist/types/shared/constants.d.ts

@@ -0,0 +1,81 @@
+export declare const SIGNUPS_PAUSED_MESSAGE = "New sign-ups are paused while we upgrade sign-in";
+export declare const cardTypes: readonly ["text", "link", "image", "video", "audio", "document", "palette", "quote"];
+export type CardType = (typeof cardTypes)[number];
+export declare const VISUAL_STYLE_TAXONOMY: readonly ["abstract", "cinematic", "dark", "illustrative", "minimal", "monochrome", "moody", "pastel", "photographic", "retro", "surreal", "vintage", "vibrant"];
+export type VisualStyle = (typeof VISUAL_STYLE_TAXONOMY)[number];
+export declare const VISUAL_STYLE_LABELS: Record<VisualStyle, string>;
+export declare function normalizeVisualStyle(value: string): VisualStyle | null;
+export declare function normalizeVisualStyleFilters(values?: string[]): VisualStyle[];
+export declare function extractVisualStylesFromTags(tags?: string[]): VisualStyle[] | undefined;
+export declare const COLOR_HUE_BUCKETS: readonly ["red", "orange", "yellow", "green", "teal", "cyan", "blue", "purple", "pink", "brown", "neutral"];
+export type ColorHueBucket = (typeof COLOR_HUE_BUCKETS)[number];
+export declare const COLOR_HUE_LABELS: Record<ColorHueBucket, string>;
+export declare function normalizeColorHueBucket(value: string): ColorHueBucket | null;
+export declare function normalizeHueFilters(values?: string[]): ColorHueBucket[];
+/**
+ * Maximum number of cards allowed for free tier users
+ */
+export declare const FREE_TIER_LIMIT = 200;
+/**
+ * Maximum file size for uploads (100MB in bytes)
+ */
+export { MAX_FILE_SIZE } from "./fileFormats.js";
+/**
+ * Maximum number of files that can be uploaded at once
+ */
+export declare const MAX_FILES_PER_UPLOAD = 5;
+export declare const MULTIPART_UPLOAD_THRESHOLD: number;
+export declare const CARD_ERROR_CODES: {
+    readonly CARD_LIMIT_REACHED: "CARD_LIMIT_REACHED";
+    readonly CONTENT_TOO_LARGE: "CONTENT_TOO_LARGE";
+    readonly INVALID_UTF8: "INVALID_UTF8";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly FILE_TOO_LARGE: "FILE_TOO_LARGE";
+    readonly TOO_MANY_FILES: "TOO_MANY_FILES";
+    readonly UNSUPPORTED_TYPE: "UNSUPPORTED_TYPE";
+    readonly TYPE_MISMATCH: "TYPE_MISMATCH";
+};
+export type CardErrorCode = (typeof CARD_ERROR_CODES)[keyof typeof CARD_ERROR_CODES];
+export declare const CARD_ERROR_MESSAGES: Record<CardErrorCode, string>;
+/**
+ * All card types as readonly array
+ */
+export declare const CARD_TYPES: readonly CardType[];
+/**
+ * Card type labels for UI display
+ */
+export declare const CARD_TYPE_LABELS: Record<CardType, string>;
+/**
+ * Card type icons mapping (for UI components)
+ */
+export declare const CARD_TYPE_ICONS: Record<CardType, string>;
+/**
+ * Card type configuration registry for centralized management
+ */
+export interface CardTypeConfig {
+    icon: string;
+    label: string;
+    searchLabel: string;
+}
+export declare const CARD_TYPE_REGISTRY: Record<CardType, CardTypeConfig>;
+/**
+ * Helper functions for card type configuration
+ */
+export declare function getCardTypeConfig(cardType: CardType): CardTypeConfig;
+export declare function getCardTypeIcon(cardType: CardType): string;
+export declare function getCardTypeLabel(cardType: CardType): string;
+/**
+ * Typeahead option for search/filter dropdowns
+ */
+export interface TypeaheadOption {
+    label: string;
+    value: CardType | "favorites" | "trash";
+}
+/**
+ * Reserved keywords for search functionality
+ */
+export declare const RESERVED_KEYWORDS: TypeaheadOption[];
+/**
+ * Type guard to check if a value is a valid CardType
+ */
+export declare function isCardType(value: unknown): value is CardType;

package/dist/types/shared/fileFormats.d.ts

@@ -0,0 +1,65 @@
+import type { CardType } from "./constants.js";
+export declare const FILE_KINDS: readonly ["archive", "audio", "design", "image", "markdown", "motion", "office", "pdf", "source", "text", "tokens"];
+export type FileKind = (typeof FILE_KINDS)[number];
+export declare const FILE_PREVIEW_KINDS: readonly ["archive", "audio", "facts", "image", "markdown", "motion", "office", "pdf", "source"];
+export type FilePreviewKind = (typeof FILE_PREVIEW_KINDS)[number];
+export interface FileFormat {
+    cardType: Extract<CardType, "audio" | "document" | "image" | "text" | "video">;
+    extension: string;
+    id: string;
+    kind: FileKind;
+    language?: string;
+    mimeType: string;
+    mimeTypes: readonly string[];
+    preview: FilePreviewKind;
+}
+interface FileFormatDefinition extends FileFormat {
+    fileNames?: readonly string[];
+    suffixes: readonly string[];
+}
+export interface FilePreviewFacts {
+    animated?: boolean;
+    archiveDirectoryCount?: number;
+    archiveFileCount?: number;
+    characterCount?: number;
+    colorVariableCount?: number;
+    compressedBytes?: number;
+    headingCount?: number;
+    inspectedEntryCount?: number;
+    lineCount?: number;
+    slideCount?: number;
+    uncompressedBytes?: number;
+    wordCount?: number;
+}
+export declare const MAX_FILE_NAME_LENGTH = 240;
+export declare const MAX_FILE_SIZE: number;
+export declare const isGenericMimeType: (mimeType: string | null | undefined) => boolean;
+export declare const FILE_FORMATS: readonly [FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition, FileFormatDefinition];
+export type FileFormatId = (typeof FILE_FORMATS)[number]["id"];
+export declare class FileFormatValidationError extends Error {
+    readonly code: "FILE_TOO_LARGE" | "INVALID_FILE_NAME" | "INVALID_FILE_SIZE" | "INVALID_MIME_TYPE" | "MIME_MISMATCH" | "UNSUPPORTED_FILE_TYPE";
+    constructor(code: FileFormatValidationError["code"], message: string);
+}
+export type FileUploadErrorCode = "FILE_TOO_LARGE" | "INVALID_INPUT" | "TYPE_MISMATCH";
+export declare const fileUploadErrorCode: (error: FileFormatValidationError) => FileUploadErrorCode;
+export declare const normalizeMimeType: (mimeType: string | null | undefined) => string;
+export declare const validateFileName: (fileName: string) => string;
+export declare const inferFileFormat: (input: {
+    fileName: string;
+    mimeType?: string | null;
+}) => FileFormat | null;
+export declare const validateFileFormat: (input: {
+    fileName: string;
+    mimeType?: string | null;
+}) => FileFormat;
+export declare const validateUploadFile: (input: {
+    fileName: string;
+    fileSize: number;
+    mimeType?: string | null;
+}) => {
+    fileName: string;
+    format: FileFormat;
+    mimeType: string;
+};
+export declare const mimeTypeForFileName: (fileName: string) => string;
+export {};

package/dist/types/shared/markdown.d.ts

@@ -0,0 +1,17 @@
+export declare const MARKDOWN_CONTENT_MAX_BYTES: number;
+export declare const MARKDOWN_CONTENT_TOO_LARGE_MESSAGE = "Text card content must not exceed 512 KiB when encoded as UTF-8.";
+export declare const MARKDOWN_INVALID_UTF8_MESSAGE = "Markdown uploads must contain valid UTF-8 text.";
+export declare const MARKDOWN_ERROR_CODES: {
+    readonly CONTENT_TOO_LARGE: "CONTENT_TOO_LARGE";
+    readonly INVALID_UTF8: "INVALID_UTF8";
+};
+export type MarkdownErrorCode = (typeof MARKDOWN_ERROR_CODES)[keyof typeof MARKDOWN_ERROR_CODES];
+export declare class MarkdownContentError extends Error {
+    readonly code: MarkdownErrorCode;
+    constructor(code: MarkdownErrorCode, message: string);
+}
+export declare function isMarkdownFileName(fileName: string): boolean;
+export declare function markdownContentByteLength(content: string): number;
+export declare function validateMarkdownByteLength(byteLength: number): number;
+export declare function validateMarkdownContent(content: string): string;
+export declare function decodeMarkdownUtf8(bytes: Uint8Array): string;

package/dist/types/shared/workosResources.d.ts

@@ -0,0 +1,4 @@
+export declare const WORKOS_RESOURCES: {
+    readonly api: "https://teakvault.com/api";
+    readonly mcp: "https://teakvault.com/mcp";
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "teak-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.80",
+  "description": "Teak API client and OAuth discovery for browser and Node applications.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praveenjuge/teak.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/client/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun --no-env-file run build.ts",
+    "prepack": "bun run build",
+    "typecheck": "tsc build.ts ../convex/client/sdk.ts --strict --noEmit --moduleResolution bundler --module esnext --target es2022 --skipLibCheck --types bun,node"
+  },
+  "devDependencies": {
+    "@teak/convex": "workspace:*",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}