teak-sdk 1.0.88 → 1.0.90

package/README.md

@@ -1,30 +1,23 @@
 # Teak SDK
 
-Typed API client and OAuth discovery for Teak. The source lives in `src/`, and
-`bun run build` writes the npm package to `dist/`: one bundle with no runtime
-dependencies, so it works without the Teak monorepo.
+Typed API client and OAuth discovery for [Teak](https://teakvault.com). One
+bundle with no runtime dependencies.
+
+```bash
+npm i teak-sdk
+```
 
 ```ts
-import { createTeakClient, discoverAuthServer } from "teak-sdk";
+import { createTeakClient, staticTokenProvider } from "teak-sdk";
 
-const auth = await discoverAuthServer("https://teakvault.com/api");
 const client = createTeakClient({
   baseUrl: "https://teakvault.com/api",
-  tokenProvider: { getAccessToken: () => yourStoredAccessToken },
+  tokenProvider: staticTokenProvider(process.env.TEAK_API_KEY!),
 });
-```
 
-Use the discovered endpoints and client ID for your OAuth surface. The WorkOS
-Connect helpers (`createPkceChallenge`, `createConnectAuthorizeUrl`,
-`requestConnectTokens`, `fetchConnectOwnerId`, `disconnectConnectGrant`) cover
-PKCE sign-in, refresh, account binding and disconnect. Refresh
-discovery after sign-in or refresh failures. Keep tokens in your platform's secure
-storage; this package does not store credentials or open a browser.
-
-The optional `TokenProvider.onUnauthorized(rejectedToken: string)` callback receives
-the token used by a retry-eligible 401 response. Return a new or already-refreshed
-token to retry once, or `null` to stop. Check the rejected token against the current
-session before refreshing so an older response cannot invalidate newer credentials.
+await client.cards.create({ content: "A note from my script" });
+```
 
-Install it from npm as `teak-sdk`. Each release shares the lockstep version of
-the other Teak products and is published by the `SDK Release` workflow.
+The guide, with token providers and WorkOS Connect sign-in, is at
+[teakvault.com/docs/sdk](https://teakvault.com/docs/sdk). Each release shares
+the lockstep version of the other Teak products.

package/index.js

@@ -1,6 +1,6 @@
 // ../convex/shared/utils/formatBytes.ts
 var BYTE_UNITS = ["B", "KB", "MB", "GB"];
-var formatBytes = (bytes) => {
+var formatBytes = (bytes, locale) => {
   if (!(bytes && Number.isFinite(bytes) && bytes > 0)) {
     return "0 B";
   }
@@ -11,7 +11,12 @@ var formatBytes = (bytes) => {
     unit += 1;
   }
   const digits = unit > 0 && value < 10 ? 1 : 0;
-  return `${value.toFixed(digits)} ${BYTE_UNITS[unit]}`;
+  const number = locale ? new Intl.NumberFormat(locale, {
+    maximumFractionDigits: digits,
+    minimumFractionDigits: digits,
+    useGrouping: false
+  }).format(value) : value.toFixed(digits);
+  return `${number} ${BYTE_UNITS[unit]}`;
 };
 // ../convex/shared/boundedResponse.ts
 class ResponseSizeLimitError extends Error {
@@ -69,7 +74,8 @@ var validateOAuthUrl = (raw, local = false) => {
     throw new Error("Missing OAuth discovery URL");
   }
   const url = new URL(raw);
-  if (url.username || url.password || url.hash || url.protocol !== "https:" && !(local && url.protocol === "http:" && isLoopbackHostname(url.hostname)) || !local && isLoopbackHostname(url.hostname) || privateHost(url.hostname) && !(local && isLoopbackHostname(url.hostname))) {
+  const hostname = url.hostname.replace(/\.+$/, "");
+  if (url.username || url.password || url.hash || url.protocol !== "https:" && !(local && url.protocol === "http:" && isLoopbackHostname(hostname)) || !local && isLoopbackHostname(hostname) || privateHost(hostname) && !(local && isLoopbackHostname(hostname))) {
     throw new Error("Unsafe OAuth discovery URL");
   }
   return url;
@@ -329,7 +335,6 @@ var fetchConnectOwnerId = async (apiUrl, accessToken, options = {}) => {
 };
 // ../convex/shared/markdown.ts
 var MARKDOWN_CONTENT_MAX_BYTES = 512 * 1024;
-
 // ../files-protocol/src/decisions.ts
 var CLEF_MODEL_ID = "@cf/cloudflare/clef";
 var CLEF_FLASH_MODEL_ID = "@cf/cloudflare/clef-flash";
@@ -360,11 +365,49 @@ var FILES_OBJECT_KEY_ROOTS = ["", FILES_DEV_KEY_PREFIX].flatMap((envPrefix) => [
 // ../files-protocol/src/inspect.ts
 var FILES_INSPECT_MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
 var FILES_INSPECT_MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+// ../files-protocol/src/metadata.ts
+var SHARED_LANGUAGE_RULES = `- In Japanese, Chinese and Korean, each tag is one term with no spaces, such as "デザイン", "设计" or "디자인".
+- Never use "secret" or "hidden", or a translation of either, as a tag.`;
+var CONTENT_LANGUAGE_RULES = `- Write the tags and the summary in the same language as the content. If the content mixes languages, use the main one. If you can't tell the language, use English.
+${SHARED_LANGUAGE_RULES}
+- Language is the content's main language as a lowercase ISO 639-1 code, such as "en", "ja" or "es".`;
+var IMAGE_LANGUAGE_RULES = `- Write the tags and the summary in the language of the text in the image. If the text mixes languages, use the main one. If the image has no legible text, use English.
+${SHARED_LANGUAGE_RULES}
+- Language is the main language of the text in the image as a lowercase ISO 639-1 code, such as "en", "ja" or "es", and "en" when it has no legible text.`;
+var TEXT_ANALYSIS_SYSTEM_PROMPT = `You are an expert content analyzer. Generate relevant tags and a concise summary for the given content. /no_think
+
+Guidelines:
+- Tags should be 5-6 specific, relevant single words only (no spaces, no hyphens)
+- Summary should be 1-2 sentences that capture the essence
+- Focus on the main topics, themes, and key information
+- Use clear, searchable language
+${CONTENT_LANGUAGE_RULES}
+
+Respond with a single JSON object using exactly this shape and no other keys:
+{"tags": ["word", "word"], "summary": "...", "language": "xx"}`;
+var LINK_ANALYSIS_SYSTEM_PROMPT = `You are an expert web content analyzer. Generate relevant tags and a concise summary for the given web page content. /no_think
+
+Guidelines:
+- Tags should be 5-6 single words capturing main topics, categories, and key concepts (no spaces, no hyphens)
+- Include relevant technology, industry, or topic tags where applicable
+- Summary should be 1-2 sentences capturing the essence and value of the content
+- Focus on what makes this link useful and searchable
+- Use clear, specific language that helps with discovery
+- Consider the source, author, and context when available
+${CONTENT_LANGUAGE_RULES}
+
+Respond with a single JSON object using exactly this shape and no other keys:
+{"tags": ["word", "word"], "summary": "...", "language": "xx"}`;
+var ISO_639_1 = new Set(("aa ab ae af ak am an ar as av ay az ba be bg bi bm bn bo br bs ca ce ch " + "co cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr fy " + "ga gd gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is it " + "iu ja jv ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln lo " + "lt lu lv mg mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny " + "oc oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg si sk sl " + "sm sn so sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ty " + "ug uk ur uz ve vi vo wa wo xh yi yo za zh zu").split(" "));
 // ../files-protocol/src/remoteAsset.ts
 var FILES_REMOTE_ASSET_MAX_BYTES = {
   image: 20 * 1024 * 1024,
   video: 50 * 1024 * 1024
 };
+var GENERIC_CONTENT_TYPES = new Set([
+  "application/octet-stream",
+  "binary/octet-stream"
+]);
 // ../files-protocol/src/workflows.ts
 var WORKFLOW_RPC_MAX_TTL_SECONDS = 5 * 60;
 var WORKFLOW_RPC_MAX_BODY_BYTES = 4 * 1024 * 1024;
@@ -850,6 +893,11 @@ var TAG_ERROR_MESSAGES = {
 };
 var HIDDEN_TAG_KEYS = ["secret", "hidden"];
 var hiddenTagKeys = new Set(HIDDEN_TAG_KEYS);
+var MAX_CARD_TAGS = 100;
+var CARD_TAG_ERROR_MESSAGES = {
+  TAG_TOO_LONG: `Each tag must be at most ${MAX_TAG_NAME_LENGTH} characters`,
+  TOO_MANY_TAGS: `A card can have at most ${MAX_CARD_TAGS} tags`
+};
 // ../convex/shared/constants.ts
 var cardTypes = [
   "text",
@@ -929,6 +977,7 @@ var ERROR_CODES = [
   "FILE_TOO_LARGE",
   "FOLDER_LIMIT",
   "FORBIDDEN",
+  "HIGHLIGHT_LIMIT",
   "IN_PROGRESS",
   "INTERNAL_ERROR",
   "INVALID_API_KEY",
@@ -939,9 +988,12 @@ var ERROR_CODES = [
   "METHOD_NOT_ALLOWED",
   "NETWORK_ERROR",
   "NOT_FOUND",
+  "NO_ARTICLE",
   "NO_CONTENT",
   "NOT_IN_TRASH",
+  "PAGE_SNAPSHOT_TOO_LARGE",
   "PARSE_ERROR",
+  "QUOTE_NOT_FOUND",
   "RATE_LIMITED",
   "REQUEST_FAILED",
   "SERVICE_UNAVAILABLE",
@@ -1058,7 +1110,7 @@ var buildCardsSearchParams = (input) => {
   if (input.mode === "keyword" || input.mode === "semantic") {
     search.set("mode", input.mode);
   }
-  if (input.sort === "oldest" || input.sort === "shuffle") {
+  if (input.sort && input.sort !== "newest") {
     search.set("sort", input.sort);
   }
   if (input.sort === "shuffle" && typeof input.shuffleSeed === "number") {
@@ -1073,12 +1125,38 @@ var buildCardsSearchParams = (input) => {
   search.set("limit", String(normalizeLimit(input.limit)));
   return search.toString();
 };
-var parseJson = async (response) => {
-  if (response.status === 204) {
-    return null;
+var readStream = async (reader) => {
+  const decoder = new TextDecoder;
+  let text = "";
+  for (;; ) {
+    const { done, value } = await reader.read();
+    if (done) {
+      return text + decoder.decode();
+    }
+    text += decoder.decode(value, { stream: true });
+  }
+};
+var readBody = (response, signal) => new Promise((resolve, reject) => {
+  const reader = response.body?.getReader();
+  const onAbort = () => {
+    reject(new TeakApiError("TIMEOUT"));
+    reader?.cancel().catch(() => {
+      return;
+    });
+  };
+  if (signal.aborted) {
+    onAbort();
+    return;
+  }
+  if (!reader) {
+    resolve("");
+    return;
   }
-  const text = await response.text();
-  if (!text.trim()) {
+  signal.addEventListener("abort", onAbort, { once: true });
+  readStream(reader).then(resolve, () => reject(new TeakApiError(signal.aborted ? "TIMEOUT" : "NETWORK_ERROR"))).finally(() => signal.removeEventListener("abort", onAbort));
+});
+var parseJson = (response, text) => {
+  if (response.status === 204 || !text.trim()) {
     return null;
   }
   try {
@@ -1113,6 +1191,18 @@ var asFolders = (value) => {
   }
   return { items: value.items.map(asFolder) };
 };
+var asHighlight = (value) => {
+  if (!isObject(value) || typeof value.id !== "string" || typeof value.quote !== "string") {
+    throw new TeakApiError("PARSE_ERROR", "Teak returned an unexpected highlight payload.");
+  }
+  return value;
+};
+var asHighlights = (value) => {
+  if (!(isObject(value) && Array.isArray(value.items))) {
+    throw new TeakApiError("PARSE_ERROR");
+  }
+  return { items: value.items.map(asHighlight) };
+};
 var asFolderCards = (value) => {
   if (!(isObject(value) && isStringArray(value.updatedIds) && isStringArray(value.failedIds))) {
     throw new TeakApiError("PARSE_ERROR");
@@ -1160,7 +1250,7 @@ var asSavedPdf = (value) => {
   return { cardId: value.cardId, created: value.created };
 };
 var asCardContent = (value) => {
-  if (!isObject(value) || typeof value.cardId !== "string" || typeof value.text !== "string" || typeof value.charCount !== "number" || typeof value.truncated !== "boolean" || !["document", "transcript", "content"].includes(String(value.kind))) {
+  if (!isObject(value) || typeof value.cardId !== "string" || typeof value.text !== "string" || typeof value.charCount !== "number" || typeof value.truncated !== "boolean" || typeof value.kind !== "string") {
     throw new TeakApiError("PARSE_ERROR");
   }
   return value;
@@ -1208,14 +1298,18 @@ var createTeakClient = (options) => {
       headers.set("Content-Type", "application/json");
     }
     let response;
+    let text;
     try {
-      response = await fetchImpl(`${baseUrl}${path}`, {
-        ...init,
-        headers,
-        signal: controller.signal
-      });
-    } catch (error) {
-      throw new TeakApiError(error instanceof DOMException && error.name === "AbortError" ? "TIMEOUT" : "NETWORK_ERROR");
+      try {
+        response = await fetchImpl(`${baseUrl}${path}`, {
+          ...init,
+          headers,
+          signal: controller.signal
+        });
+      } catch (error) {
+        throw new TeakApiError(error instanceof DOMException && error.name === "AbortError" ? "TIMEOUT" : "NETWORK_ERROR");
+      }
+      text = response.status === 204 ? "" : await readBody(response, controller.signal);
     } finally {
       clearTimeout(timeout);
     }
@@ -1225,7 +1319,7 @@ var createTeakClient = (options) => {
         return request(path, init, parser, false, next);
       }
     }
-    const payload = await parseJson(response);
+    const payload = parseJson(response, text);
     if (!response.ok) {
       const object = isObject(payload) ? payload : {};
       throw new TeakApiError(codeFrom(object.code, response.status === 404 ? "NOT_FOUND" : "REQUEST_FAILED"), String(object.error || response.statusText), {
@@ -1240,6 +1334,7 @@ var createTeakClient = (options) => {
   const idempotency = (requestOptions) => requestOptions?.idempotencyKey ? { "Idempotency-Key": requestOptions.idempotencyKey } : {};
   const cardPath = (id) => `/v1/cards/${encodeURIComponent(id)}`;
   const folderPath = (id) => `/v1/folders/${encodeURIComponent(id)}`;
+  const highlightPath = (id) => `/v1/highlights/${encodeURIComponent(id)}`;
   const putFile = async (uploadUrl, bytes, mimeType) => {
     const headers = new Headers({ "Content-Type": mimeType });
     const byteLength = byteLengthForBody(bytes);
@@ -1275,7 +1370,7 @@ var createTeakClient = (options) => {
         headers: idempotency(requestOptions),
         method: "POST"
       }, asCreate),
-      content: (id) => request(`${cardPath(id)}/content`, { method: "GET" }, asCardContent),
+      content: (id, contentOptions) => request(`${cardPath(id)}/content${contentOptions?.kind ? `?kind=${encodeURIComponent(contentOptions.kind)}` : ""}`, { method: "GET" }, asCardContent),
       delete: (id, deleteOptions) => request(`${cardPath(id)}${deleteOptions?.permanent ? "?permanent=true" : ""}`, { method: "DELETE" }, () => null),
       duplicate: (url) => request(`/v1/cards/duplicate?${new URLSearchParams({ url }).toString()}`, { method: "GET" }, (v) => isObject(v) && typeof v.cardId === "string" ? v.cardId : null),
       favorites: (input = {}) => request(`/v1/cards?${qs({ include: "content,metadata", ...input, favorited: true })}`, { method: "GET" }, asPage),
@@ -1328,6 +1423,12 @@ var createTeakClient = (options) => {
       removeCards: (id, cardIds) => request(`${folderPath(id)}/cards`, { body: JSON.stringify({ cardIds }), method: "DELETE" }, asFolderCards),
       update: (id, input) => request(folderPath(id), { body: JSON.stringify(input), method: "PATCH" }, asFolder)
     },
+    highlights: {
+      create: (cardId, input) => request(`${cardPath(cardId)}/highlights`, { body: JSON.stringify(input), method: "POST" }, asHighlight),
+      delete: (id) => request(highlightPath(id), { method: "DELETE" }, () => null),
+      list: (cardId) => request(`${cardPath(cardId)}/highlights`, { method: "GET" }, asHighlights),
+      update: (id, input) => request(highlightPath(id), { body: JSON.stringify(input), method: "PATCH" }, asHighlight)
+    },
     me: () => request("/v1/me", { method: "GET" }, asMe),
     tags: {
       delete: (tag) => request("/v1/tags/delete", { body: JSON.stringify({ tag }), method: "POST" }, asTagOperation),
@@ -1336,6 +1437,9 @@ var createTeakClient = (options) => {
       operation: (id) => request(`/v1/tags/operations/${encodeURIComponent(id)}`, { method: "GET" }, asTagOperation),
       rename: (from, to) => request("/v1/tags/rename", { body: JSON.stringify({ from, to }), method: "POST" }, asTagOperation)
     },
+    pageSnapshots: {
+      createUpload: (input) => request("/v1/page-snapshots/upload", { body: JSON.stringify(input), method: "POST" }, asUpload)
+    },
     uploads: {
       create: (input) => request("/v1/uploads", { body: JSON.stringify(input), method: "POST" }, asUpload),
       putFile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teak-sdk",
-  "version": "1.0.88",
+  "version": "1.0.90",
   "description": "Teak API client and OAuth discovery for browser and Node applications.",
   "repository": {
     "type": "git",

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

@@ -20,6 +20,12 @@ export declare const COLOR_HUE_ALIAS_MAP: Record<string, ColorHueBucket>;
 export declare function normalizeColorHueBucket(value: string): ColorHueBucket | null;
 export declare function normalizeHueFilters(values?: string[]): ColorHueBucket[];
 export declare const FREE_TIER_LIMIT = 200;
+/** The most links one paste into the web composer saves (card/pasteLinks.ts). */
+export declare const LINK_PASTE_LIMIT = 100;
+/** The most lines one paste may send; the composer sends no more. */
+export declare const LINK_PASTE_MAX_INPUT = 1000;
+/** Refused while the account's last pasted links are still being saved. */
+export declare const LINK_PASTE_ACTIVE_CODE = "PASTE_ACTIVE";
 export declare const TRASH_RETENTION_MS: number;
 export { MAX_FILE_SIZE } from "./fileFormats.js";
 export declare const MAX_FILES_PER_UPLOAD = 20;

package/types/convex/shared/tags.d.ts

@@ -19,6 +19,19 @@ export declare const isCardHidden: (card: {
     tags?: readonly string[];
 }) => boolean;
 export declare const explainInvalidTagName: (name: string) => string | null;
+export declare const MAX_CARD_TAGS = 100;
+export declare const CARD_TAG_ERROR_MESSAGES: {
+    readonly TAG_TOO_LONG: "Each tag must be at most 64 characters";
+    readonly TOO_MANY_TAGS: "A card can have at most 100 tags";
+};
+/** Trims each tag, drops empty ones and keeps the first of each case variant. */
+export declare const normalizeTagList: (tags: readonly string[]) => string[];
+/**
+ * Why a card can't hold these normalized tags, or null. Tags the card already
+ * has (saved before the limits existed) may stay, and a card already past the
+ * count may keep or drop tags, never add.
+ */
+export declare const explainInvalidCardTags: (tags: readonly string[], previousTags?: readonly string[]) => string | null;
 export declare const MAX_TAG_KEY_LENGTH = 256;
 export declare const explainInvalidTagSource: (name: string) => string | null;
 export declare const tagExistsMessage: (name: string) => string;

package/types/convex/shared/utils/formatBytes.d.ts

@@ -1 +1,5 @@
-export declare const formatBytes: (bytes?: number | null) => string;
+/**
+ * A byte size such as "2.1 MB". Pass a locale to write the number in that
+ * language ("2,1 MB" in German); without one it keeps the "." of before.
+ */
+export declare const formatBytes: (bytes?: number | null, locale?: string) => string;

package/types/index.d.ts

@@ -8,7 +8,7 @@ import type { FOLDER_COLORS } from "./convex/shared/folders.js";
 export type { CardType } from "./convex/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", "relevance", "shuffle"];
-export declare const ERROR_CODES: readonly ["AUTH_REQUIRED", "BAD_REQUEST", "CARD_LIMIT_REACHED", "CONFIG_ERROR", "CONFLICT", "CONTENT_TOO_LARGE", "FILE_TOO_LARGE", "FOLDER_LIMIT", "FORBIDDEN", "IN_PROGRESS", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_INPUT", "INVALID_STORAGE_KEY", "INVALID_UTF8", "LIMIT_REACHED", "METHOD_NOT_ALLOWED", "NETWORK_ERROR", "NOT_FOUND", "NO_CONTENT", "NOT_IN_TRASH", "PARSE_ERROR", "RATE_LIMITED", "REQUEST_FAILED", "SERVICE_UNAVAILABLE", "SMART_FOLDER", "TAG_EXISTS", "TAG_OPERATION_RUNNING", "TIMEOUT", "TYPE_MISMATCH", "UNAUTHORIZED", "UNSUPPORTED_TYPE"];
+export declare const ERROR_CODES: readonly ["AUTH_REQUIRED", "BAD_REQUEST", "CARD_LIMIT_REACHED", "CONFIG_ERROR", "CONFLICT", "CONTENT_TOO_LARGE", "FILE_TOO_LARGE", "FOLDER_LIMIT", "FORBIDDEN", "HIGHLIGHT_LIMIT", "IN_PROGRESS", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_INPUT", "INVALID_STORAGE_KEY", "INVALID_UTF8", "LIMIT_REACHED", "METHOD_NOT_ALLOWED", "NETWORK_ERROR", "NOT_FOUND", "NO_ARTICLE", "NO_CONTENT", "NOT_IN_TRASH", "PAGE_SNAPSHOT_TOO_LARGE", "PARSE_ERROR", "QUOTE_NOT_FOUND", "RATE_LIMITED", "REQUEST_FAILED", "SERVICE_UNAVAILABLE", "SMART_FOLDER", "TAG_EXISTS", "TAG_OPERATION_RUNNING", "TIMEOUT", "TYPE_MISMATCH", "UNAUTHORIZED", "UNSUPPORTED_TYPE"];
 export type CardSort = (typeof CARD_SORTS)[number];
 /**
  * How a search finds cards: `hybrid` (the API's default) matches words and
@@ -21,13 +21,32 @@ export interface TokenProvider {
     getAccessToken: () => Promise<string | null> | string | null;
     onUnauthorized?: (rejectedToken: string) => Promise<string | null> | string | null;
 }
+/** A link's saved copy of its page. The HTML itself stays in Teak. */
+export interface CardArchive {
+    bytes: number;
+    capturedAt: number;
+    kind: "full" | "text_only";
+}
+/** A link's article, from its saved copy; read it with `cards.content(id, { kind: "article" })`. */
+export interface CardArticle {
+    readingMinutes: number;
+    wordCount: number;
+}
 export interface Card {
     aiSummary: string | null;
     aiTags: string[];
     aiTranscript: string | null;
     appUrl: string;
+    /**
+     * A link's saved copy of its page: `full`, or `text_only` when the page
+     * was too large; null until it is saved and for other cards. Servers that
+     * predate saved copies leave it out.
+     */
+    archive?: CardArchive | null;
     /** When the card was archived, or null. */
     archivedAt: number | null;
+    /** A link's article; null when it has none or it isn't ready. */
+    article?: CardArticle | null;
     /** Bar heights 0-100: 45 for a grid card, 200 for a player. */
     audioWaveform: {
         detail: number[];
@@ -58,6 +77,11 @@ export interface Card {
     fileUrl: string | null;
     /** Ids of the folders the card is in. */
     folderIds: string[];
+    /**
+     * Passages highlighted in a link's article; 0 for other cards. Servers
+     * that predate highlights leave it out.
+     */
+    highlightCount?: number;
     id: string;
     /** Archived cards are hidden from the library but still count. */
     isArchived: boolean;
@@ -115,6 +139,11 @@ export interface Card {
     notes: string | null;
     placeholderUrl: string | null;
     processingStatus: Record<string, unknown> | null;
+    /**
+     * When the card was last saved: `createdAt`, or later when the same link
+     * was saved again. Lists order by it. Servers that predate it leave it out.
+     */
+    savedAt?: number;
     screenshotUrl: string | null;
     /**
      * The title of the page in `sourceUrl`. Servers that predate sources
@@ -220,6 +249,28 @@ export interface TagOperation {
     total: number;
     updatedAt: number;
 }
+/** A passage highlighted in a link's article, with an optional note. */
+export interface Highlight {
+    /** False until the quote is found in the card's saved article. */
+    anchored: boolean;
+    cardId: string;
+    createdAt: number;
+    id: string;
+    note: string | null;
+    quote: string;
+    /** `reader`, `api` or `import`; accept values this SDK doesn't know. */
+    source: string;
+    updatedAt: number;
+}
+export interface CreateHighlightInput {
+    note?: string;
+    /** Text just before the quote, to pick one of its repeats. */
+    prefix?: string;
+    /** Text from the article; whitespace, curly quotes and case needn't match. */
+    quote: string;
+    /** Text just after the quote, to pick one of its repeats. */
+    suffix?: string;
+}
 export interface FolderCardsResult {
     failedIds: string[];
     /** Failed cards that are already in the most folders a card can be in. */
@@ -251,6 +302,12 @@ export interface CreateCardInput {
     mimeType?: string;
     /** Free-form notes attached to the card. */
     notes?: string | null;
+    /**
+     * The `fileKey` from `pageSnapshots.createUpload`: the page as the browser
+     * showed it, which becomes a link's saved copy. Ignored when it isn't one
+     * of your snapshot uploads.
+     */
+    pageSnapshotKey?: string;
     /**
      * A free label for what saved the card (extension, CLI, API, and so on),
      * kept in its metadata. For the page the card came from, use `sourceUrl`.
@@ -290,6 +347,12 @@ export interface Me {
     cardLimit: number | null;
     email: string;
     id: string;
+    /**
+     * The account's Teak language, chosen in Settings: a BCP 47 code such as
+     * `en`, `de` or `pt-BR`. More may be added, so treat an unknown code as
+     * English.
+     */
+    locale: string;
     name?: string;
     plan: "free" | "pro";
     settingsUrl: string;
@@ -325,6 +388,10 @@ export interface CreateUploadInput {
     mimeType: string;
 }
 /** A link image upload: JPEG, PNG, WebP, GIF or AVIF, under 20 MB. */
+export interface CreatePageSnapshotUploadInput {
+    /** The gzipped page's exact size; at most 20 MiB. */
+    bytes: number;
+}
 export interface CreateThumbnailUploadInput {
     fileSize: number;
     mimeType: string;
@@ -340,7 +407,16 @@ export interface CreateCardResponse {
     appUrl: string;
     card?: Card;
     cardId: string;
+    /**
+     * True when the link was already in Teak: no card was made, and that card
+     * (`cardId`) moved to the top. Tags and notes sent with the save were not
+     * applied; update the card to add them.
+     */
+    resaved?: true;
+    /** `status` stays `created` for a re-save too. */
     status: "created";
+    /** True when the re-saved card was archived; it is back in the library. */
+    wasArchived?: true;
 }
 export interface RefreshCardResponse {
     cardId: string;
@@ -354,6 +430,8 @@ export interface SavedPdf {
     /** False when an earlier save already made that card. */
     created: boolean;
 }
+/** The kinds of stored text a card can have. */
+export type CardContentKind = "article" | "document" | "transcript" | "content";
 /** A card's full stored text (GET /v1/cards/:id/content). */
 export interface CardContent {
     cardId: string;
@@ -361,9 +439,11 @@ export interface CardContent {
     charCount: number;
     /**
      * document: extracted from the card's file; transcript: its speech;
-     * content: a text or quote card's written text.
+     * content: a text or quote card's written text; article: a link's article
+     * as Markdown, with image links valid for 7 days. A kind this SDK doesn't
+     * know yet comes through as a string rather than an error.
      */
-    kind: "document" | "transcript" | "content";
+    kind: CardContentKind | (string & {});
     text: string;
     /** The document is longer than Teak keeps. */
     truncated: boolean;
@@ -414,7 +494,9 @@ export declare const buildCardsSearchParams: (input: {
      * `is:fav`, `is:archived`, `site:github.com`, `folder:"Reading list"`,
      * `price:<100` (also `>`, `<=`, `>=` and `=`), `text:"total due"` (only
      * the words Teak read in images, video thumbnails, link previews and scanned
-     * PDFs) and `"quoted phrases"`.
+     * PDFs) and `"quoted phrases"`. A `-` leaves cards out (`design -figma`,
+     * `-tag:old`), uppercase `OR` matches either side and parentheses group:
+     * `(site:github.com OR site:gitlab.com) -is:archived`.
      */
     query?: string;
     /** Required with `sort: "shuffle"`: the same seed gives the same order. */
@@ -444,9 +526,13 @@ export declare const createTeakClient: (options: {
         create: (input: CreateCardInput, requestOptions?: RequestOptions) => Promise<CreateCardResponse>;
         /**
          * The card's full stored text: document text, transcript, or a text
-         * card's content. Throws NO_CONTENT when the card has none.
+         * card's content. `{ kind: "article" }` reads a link's article as
+         * Markdown; `kind` picks one kind when a card has several. Throws
+         * NO_CONTENT when the card has none (of that kind).
          */
-        content: (id: string) => Promise<CardContent>;
+        content: (id: string, contentOptions?: {
+            kind?: CardContentKind;
+        }) => Promise<CardContent>;
         /** Moves the card to Trash, or deletes it for good with `permanent`. */
         delete: (id: string, deleteOptions?: {
             permanent?: boolean;
@@ -539,6 +625,25 @@ export declare const createTeakClient: (options: {
             query?: string;
         }) => Promise<Folder>;
     };
+    highlights: {
+        /**
+         * Highlights a passage of a link's saved article, found by its text:
+         * the first match unless `prefix` or `suffix` points at another. An
+         * overlapping highlight merges with it. 409 NO_ARTICLE without a saved
+         * article, 422 QUOTE_NOT_FOUND, 409 HIGHLIGHT_LIMIT past 200.
+         */
+        create: (cardId: string, input: CreateHighlightInput) => Promise<Highlight>;
+        /** Removes a highlight and its note. */
+        delete: (id: string) => Promise<null>;
+        /** A card's highlights, in the order they appear in its article. */
+        list: (cardId: string) => Promise<{
+            items: Highlight[];
+        }>;
+        /** Writes or changes a highlight's note; `note: null` clears it. */
+        update: (id: string, input: {
+            note: string | null;
+        }) => Promise<Highlight>;
+    };
     me: () => Promise<Me>;
     tags: {
         /**
@@ -556,6 +661,14 @@ export declare const createTeakClient: (options: {
         /** Renames a tag on every card; it finishes in the background. */
         rename: (from: string, to: string) => Promise<TagOperation>;
     };
+    pageSnapshots: {
+        /**
+         * A signed URL for the page a browser extension saw, gzipped: `PUT`
+         * it with `Content-Type: application/gzip`, then pass the `fileKey`
+         * to `cards.create` as `pageSnapshotKey`.
+         */
+        createUpload: (input: CreatePageSnapshotUploadInput) => Promise<CreateUploadResponse>;
+    };
     uploads: {
         create: (input: CreateUploadInput) => Promise<CreateUploadResponse>;
         putFile: (uploadUrl: string, bytes: BodyInit, mimeType: string) => Promise<{