pi-meta-oauth 0.2.0 → 0.2.2

package/README.md

@@ -2,6 +2,9 @@
 
 # pi-meta-oauth
 
+<!-- markdownlint-disable-next-line MD013 -->
+[![npm version](https://img.shields.io/npm/v/pi-meta-oauth)](https://www.npmjs.com/package/pi-meta-oauth) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub stars](https://img.shields.io/github/stars/BlockedPath/pi-meta-oauth?style=social)](https://github.com/BlockedPath/pi-meta-oauth/stargazers) [![Last Commit](https://img.shields.io/github/last-commit/BlockedPath/pi-meta-oauth)](https://github.com/BlockedPath/pi-meta-oauth/commits/main) [![Issues](https://img.shields.io/github/issues/BlockedPath/pi-meta-oauth)](https://github.com/BlockedPath/pi-meta-oauth/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BlockedPath/pi-meta-oauth/pulls) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org/en/v1.0.0/) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/) [![CI](https://github.com/BlockedPath/pi-meta-oauth/actions/workflows/ci.yml/badge.svg)](https://github.com/BlockedPath/pi-meta-oauth/actions/workflows/ci.yml) [![Pi compatible](https://img.shields.io/badge/pi-Compatible-blueviolet)](https://pi.dev)
+
 Meta Model API OAuth and Muse-style voice input for [pi](https://pi.dev).
 
 - Use Muse Spark models through Pi's `openai-responses` provider
@@ -83,13 +86,19 @@ bun run typecheck
 bun test
 ```
 
-## Publish to pi.dev
+## Publish to npm and pi.dev
 
-The `pi-package` keyword makes the package discoverable at <https://pi.dev/packages>.
+The `pi-package` keyword makes the package discoverable at <https://pi.dev/packages>. Publishing is handled by `.github/workflows/publish.yml` when a `v*` tag is pushed.
 
-```bash
-npm publish --access public
-```
+Before the first automated release, configure npm trusted publishing for `pi-meta-oauth` with:
+
+- GitHub owner: `BlockedPath`
+- Repository: `pi-meta-oauth`
+- Workflow filename: `publish.yml`
+- Environment: leave blank
+- Allowed action: `npm publish`
+
+Bump `package.json`, commit the change, create a `v<version>` tag, and push the commit and tag. The workflow verifies that the tag matches the package version, runs typechecking and tests, publishes to npm with provenance, and creates the GitHub Release. Re-running a partially completed workflow is safe when npm reports that the same commit was already published.
 
 Users can then update with:
 

package/extensions/meta.ts

@@ -3,7 +3,10 @@ import type {
 	OAuthLoginCallbacks,
 	RefreshModelsContext,
 } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ProviderConfig,
+} from "@earendil-works/pi-coding-agent";
 
 export const META_PROVIDER_ID = "meta";
 export const META_API_BASE_URL = "https://api.meta.ai/v1";
@@ -60,7 +63,11 @@ interface MetaCatalogModel {
 			modalities?: { input?: string[] };
 			limit?: { context?: number; output?: number };
 			variants?: Record<string, { reasoningEffort?: string }>;
-			cost?: { input?: string | number; output?: string | number; cached?: string | number };
+			cost?: {
+				input?: string | number;
+				output?: string | number;
+				cached?: string | number;
+			};
 		};
 	};
 }
@@ -83,7 +90,7 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
 		contextWindow: 1_048_576,
 		maxTokens: 256_000,
-		compat: { supportsReasoningEffort: true },
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
 	},
 	{
 		id: "muse-spark-1.2-contributor",
@@ -102,7 +109,7 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 		cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
 		contextWindow: 1_048_576,
 		maxTokens: 256_000,
-		compat: { supportsReasoningEffort: true },
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
 	},
 	{
 		id: "muse-spark-1.1",
@@ -121,7 +128,7 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
 		contextWindow: 1_048_576,
 		maxTokens: 256_000,
-		compat: { supportsReasoningEffort: true },
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
 	},
 ];
 
@@ -129,7 +136,9 @@ function delay(milliseconds: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
-async function responseBody(response: Response): Promise<Record<string, unknown>> {
+async function responseBody(
+	response: Response,
+): Promise<Record<string, unknown>> {
 	const text = await response.text();
 	if (!text) return {};
 	try {
@@ -157,14 +166,23 @@ async function postForm<T>(
 ): Promise<{ response: Response; body: T & Record<string, unknown> }> {
 	const response = await fetchImpl(url, {
 		method: "POST",
-		headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
+		headers: {
+			Accept: "application/json",
+			"Content-Type": "application/x-www-form-urlencoded",
+		},
 		body: new URLSearchParams(fields),
 		redirect: "manual",
 	});
-	return { response, body: (await responseBody(response)) as T & Record<string, unknown> };
+	return {
+		response,
+		body: (await responseBody(response)) as T & Record<string, unknown>,
+	};
 }
 
-export async function mintMetaApiKey(identityToken: string, fetchImpl: Fetch = fetch): Promise<string> {
+export async function mintMetaApiKey(
+	identityToken: string,
+	fetchImpl: Fetch = fetch,
+): Promise<string> {
 	const response = await fetchImpl(API_KEY_MINT_URL, {
 		method: "POST",
 		headers: {
@@ -175,12 +193,18 @@ export async function mintMetaApiKey(identityToken: string, fetchImpl: Fetch = f
 		},
 		body: "{}",
 	});
-	const body = (await responseBody(response)) as MintResponse & Record<string, unknown>;
+	const body = (await responseBody(response)) as MintResponse &
+		Record<string, unknown>;
 	if (!response.ok) {
-		throw new Error(`Meta API-key mint failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`);
+		throw new Error(
+			`Meta API-key mint failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
+		);
 	}
 	if (typeof body.api_key !== "string" || !body.api_key) {
-		const setup = typeof body.action_url === "string" && body.action_url ? ` Complete setup at ${body.action_url}.` : "";
+		const setup =
+			typeof body.action_url === "string" && body.action_url
+				? ` Complete setup at ${body.action_url}.`
+				: "";
 		throw new Error(`Meta did not issue an API key.${setup}`);
 	}
 	return body.api_key;
@@ -204,17 +228,24 @@ export async function loginMeta(
 	}
 	const device = authorization.body;
 	if (!device.device_code || !device.user_code || !device.verification_uri) {
-		throw new Error("Meta device authorization returned an incomplete response");
+		throw new Error(
+			"Meta device authorization returned an incomplete response",
+		);
 	}
 
-	let intervalSeconds = Number.isFinite(device.interval) && Number(device.interval) > 0 ? Number(device.interval) : 5;
-	const expiresInSeconds = Number.isFinite(device.expires_in) && Number(device.expires_in) > 0
-		? Number(device.expires_in)
-		: 900;
+	let intervalSeconds =
+		Number.isFinite(device.interval) && Number(device.interval) > 0
+			? Number(device.interval)
+			: 5;
+	const expiresInSeconds =
+		Number.isFinite(device.expires_in) && Number(device.expires_in) > 0
+			? Number(device.expires_in)
+			: 900;
 	const deadline = Date.now() + expiresInSeconds * 1000;
 	callbacks.onDeviceCode({
 		userCode: device.user_code,
-		verificationUri: device.verification_uri_complete || device.verification_uri,
+		verificationUri:
+			device.verification_uri_complete || device.verification_uri,
 		intervalSeconds,
 		expiresInSeconds,
 	});
@@ -267,7 +298,10 @@ export async function refreshMetaToken(
 	credentials: OAuthCredentials,
 	fetchImpl: Fetch = fetch,
 ): Promise<OAuthCredentials> {
-	if (!credentials.refresh) throw new Error("Meta login is missing its identity token; run /login meta again");
+	if (!credentials.refresh)
+		throw new Error(
+			"Meta login is missing its identity token; run /login meta again",
+		);
 	return {
 		...credentials,
 		access: await mintMetaApiKey(credentials.refresh, fetchImpl),
@@ -276,56 +310,83 @@ export async function refreshMetaToken(
 }
 
 function finitePositive(value: unknown, fallback: number): number {
-	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: fallback;
 }
 
 function numericCost(value: unknown, fallback: number): number {
-	const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	const number =
+		typeof value === "number"
+			? value
+			: typeof value === "string"
+				? Number(value)
+				: Number.NaN;
 	return Number.isFinite(number) && number >= 0 ? number : fallback;
 }
 
 function displayName(id: string): string {
 	return id
 		.split("-")
-		.map((part) => part ? part[0].toUpperCase() + part.slice(1) : part)
+		.map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
 		.join(" ");
 }
 
-export function toProviderModels(catalog: CatalogResponse): MetaProviderModel[] {
+export function toProviderModels(
+	catalog: CatalogResponse,
+): MetaProviderModel[] {
 	return (catalog.data ?? []).flatMap((entry) => {
 		if (typeof entry.id !== "string" || !entry.id) return [];
 		const metadata = entry.metadata?.["muse-code"];
 		if (metadata?.is_hidden) return [];
 		const fallback = FALLBACK_MODELS.find((model) => model.id === entry.id);
-		const catalogName = metadata?.name === entry.id ? undefined : metadata?.name;
+		const catalogName =
+			metadata?.name === entry.id ? undefined : metadata?.name;
 		const variants = metadata?.variants ?? {};
-		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> = {
-			off: null,
-			minimal: variants.minimal?.reasoningEffort ?? "minimal",
-			low: variants.low?.reasoningEffort ?? "low",
-			medium: variants.medium?.reasoningEffort ?? "medium",
-			high: variants.high?.reasoningEffort ?? "high",
-			xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
-			max: null,
-		};
-		return [{
-			id: entry.id,
-			name: catalogName || fallback?.name || displayName(entry.id),
-			reasoning: metadata?.reasoning ?? fallback?.reasoning ?? true,
-			thinkingLevelMap,
-			input: metadata
-				? (metadata.modalities?.input?.includes("image") ? ["text", "image"] : ["text"])
-				: (fallback?.input ?? ["text"]),
-			cost: {
-				input: numericCost(metadata?.cost?.input, fallback?.cost.input ?? 0),
-				output: numericCost(metadata?.cost?.output, fallback?.cost.output ?? 0),
-				cacheRead: numericCost(metadata?.cost?.cached, fallback?.cost.cacheRead ?? 0),
-				cacheWrite: 0,
-			},
-			contextWindow: finitePositive(metadata?.limit?.context, fallback?.contextWindow ?? 1_048_576),
-			maxTokens: finitePositive(metadata?.limit?.output, fallback?.maxTokens ?? 256_000),
-			compat: { supportsReasoningEffort: true },
-		} satisfies MetaProviderModel];
+		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> =
+			{
+				off: null,
+				minimal: variants.minimal?.reasoningEffort ?? "minimal",
+				low: variants.low?.reasoningEffort ?? "low",
+				medium: variants.medium?.reasoningEffort ?? "medium",
+				high: variants.high?.reasoningEffort ?? "high",
+				xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
+				max: null,
+			};
+		return [
+			{
+				id: entry.id,
+				name: catalogName || fallback?.name || displayName(entry.id),
+				reasoning: metadata?.reasoning ?? fallback?.reasoning ?? true,
+				thinkingLevelMap,
+				input: metadata
+					? metadata.modalities?.input?.includes("image")
+						? ["text", "image"]
+						: ["text"]
+					: (fallback?.input ?? ["text"]),
+				cost: {
+					input: numericCost(metadata?.cost?.input, fallback?.cost.input ?? 0),
+					output: numericCost(
+						metadata?.cost?.output,
+						fallback?.cost.output ?? 0,
+					),
+					cacheRead: numericCost(
+						metadata?.cost?.cached,
+						fallback?.cost.cacheRead ?? 0,
+					),
+					cacheWrite: 0,
+				},
+				contextWindow: finitePositive(
+					metadata?.limit?.context,
+					fallback?.contextWindow ?? 1_048_576,
+				),
+				maxTokens: finitePositive(
+					metadata?.limit?.output,
+					fallback?.maxTokens ?? 256_000,
+				),
+				compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+			} satisfies MetaProviderModel,
+		];
 	});
 }
 
@@ -333,21 +394,30 @@ export async function refreshMetaModels(
 	context: RefreshModelsContext,
 	fetchImpl: Fetch = fetch,
 ): Promise<MetaProviderModel[]> {
-	if (!context.allowNetwork || context.signal?.aborted) return [...FALLBACK_MODELS];
-	const apiKey = context.credential?.type === "oauth"
-		? context.credential.access
-		: context.credential?.type === "api_key"
-			? context.credential.key
-			: undefined;
+	if (!context.allowNetwork || context.signal?.aborted)
+		return [...FALLBACK_MODELS];
+	const apiKey =
+		context.credential?.type === "oauth"
+			? context.credential.access
+			: context.credential?.type === "api_key"
+				? context.credential.key
+				: undefined;
 	if (!apiKey) return [...FALLBACK_MODELS];
 
 	const response = await fetchImpl(META_MODEL_CATALOG_URL, {
-		headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}`, "x-api-version": "1.0.0" },
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${apiKey}`,
+			"x-api-version": "1.0.0",
+		},
 		signal: context.signal,
 	});
-	const body = (await responseBody(response)) as CatalogResponse & Record<string, unknown>;
+	const body = (await responseBody(response)) as CatalogResponse &
+		Record<string, unknown>;
 	if (!response.ok) {
-		throw new Error(`Meta model catalog failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`);
+		throw new Error(
+			`Meta model catalog failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
+		);
 	}
 	return toProviderModels(body);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-meta-oauth",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Meta Model API OAuth provider and Muse-style voice dictation for pi",
   "keywords": [
     "pi-package",
@@ -13,6 +13,11 @@
   ],
   "license": "MIT",
   "type": "module",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "extensions/"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/BlockedPath/pi-meta-oauth"

package/tests/meta.test.ts

@@ -1,118 +0,0 @@
-/// <reference types="bun-types" />
-import { describe, expect, test } from "bun:test";
-import {
-	loginMeta,
-	mintMetaApiKey,
-	toProviderModels,
-} from "../extensions/meta.ts";
-
-function jsonResponse(body: unknown, status = 200): Response {
-	return new Response(JSON.stringify(body), {
-		status,
-		headers: { "Content-Type": "application/json" },
-	});
-}
-
-describe("Meta OAuth provider", () => {
-	test("maps the Muse catalog into Pi model metadata", () => {
-		const models = toProviderModels({
-			data: [
-				{
-					id: "muse-spark-test",
-					metadata: {
-						"muse-code": {
-							name: "Muse Spark Test",
-							reasoning: true,
-							modalities: { input: ["text", "image"] },
-							limit: { context: 123_000, output: 45_000 },
-							variants: { high: { reasoningEffort: "deep" } },
-							cost: { input: "1.25", output: "4.25", cached: "0.15" },
-						},
-					},
-				},
-				{ id: "hidden", metadata: { "muse-code": { is_hidden: true } } },
-			],
-		});
-
-		expect(models).toHaveLength(1);
-		expect(models[0]).toMatchObject({
-			id: "muse-spark-test",
-			name: "Muse Spark Test",
-			input: ["text", "image"],
-			contextWindow: 123_000,
-			maxTokens: 45_000,
-			cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
-			thinkingLevelMap: { off: null, high: "deep", max: null },
-		});
-	});
-
-	test("runs device login, polls, and mints a Model API key", async () => {
-		const requests: Array<{ url: string; authorization?: string }> = [];
-		const responses = [
-			jsonResponse({
-				device_code: "device-token",
-				user_code: "ABCD-1234",
-				verification_uri: "https://auth.meta.com/device",
-				verification_uri_complete:
-					"https://auth.meta.com/device?code=ABCD-1234",
-				expires_in: 900,
-				interval: 1,
-			}),
-			jsonResponse({ error: "authorization_pending" }, 400),
-			jsonResponse({ access_token: "identity-token" }),
-			jsonResponse({
-				api_key: "model-api-key",
-				base_url: "https://api.meta.ai/v1",
-			}),
-		];
-		const fetchMock = (async (
-			input: string | URL | Request,
-			init?: RequestInit,
-		) => {
-			const headers = new Headers(init?.headers);
-			requests.push({
-				url: String(input),
-				authorization: headers.get("Authorization") ?? undefined,
-			});
-			const response = responses.shift();
-			if (!response) throw new Error("Unexpected request");
-			return response;
-		}) as unknown as typeof fetch;
-		const deviceCodes: unknown[] = [];
-		const credentials = await loginMeta(
-			{
-				onAuth() {},
-				onDeviceCode(value: unknown) {
-					deviceCodes.push(value);
-				},
-				onPrompt: async () => "",
-				onSelect: async () => undefined,
-			},
-			fetchMock,
-			async () => {},
-		);
-
-		expect(deviceCodes).toEqual([
-			{
-				userCode: "ABCD-1234",
-				verificationUri: "https://auth.meta.com/device?code=ABCD-1234",
-				intervalSeconds: 1,
-				expiresInSeconds: 900,
-			},
-		]);
-		expect(credentials.refresh).toBe("identity-token");
-		expect(credentials.access).toBe("model-api-key");
-		expect(requests.at(-1)?.authorization).toBe("Bearer identity-token");
-	});
-
-	test("reports account setup when minting yields no API key", async () => {
-		const fetchMock = (async () =>
-			jsonResponse({
-				require_payment: true,
-				action_url: "https://dev.meta.ai/billing",
-			})) as unknown as typeof fetch;
-		await expect(mintMetaApiKey("identity-token", fetchMock)).rejects.toThrow(
-			"Complete setup at https://dev.meta.ai/billing",
-		);
-	});
-});

package/tests/voice.test.ts

@@ -1,55 +0,0 @@
-/// <reference types="bun-types" />
-import { describe, expect, test } from "bun:test";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-	asrEndpoint,
-	formatAuthorization,
-	pcmAudioLevel,
-} from "../extensions/voice.ts";
-
-describe("Meta voice mode", () => {
-	test("maps silent and audible PCM into meter levels", () => {
-		const silent = Buffer.alloc(3_200);
-		const audible = Buffer.alloc(3_200);
-		for (let offset = 0; offset < audible.length; offset += 2) {
-			audible.writeInt16LE(offset % 4 === 0 ? 8_000 : -8_000, offset);
-		}
-
-		expect(pcmAudioLevel(silent)).toBe(0);
-		expect(pcmAudioLevel(audible)).toBeGreaterThan(0.5);
-		expect(pcmAudioLevel(audible)).toBeLessThanOrEqual(1);
-	});
-
-	test("formats the Meta ASR authorization value exactly once", () => {
-		expect(formatAuthorization("LLM|example")).toBe("OAuth LLM|example");
-		expect(formatAuthorization("OAuth LLM|example")).toBe("OAuth LLM|example");
-	});
-
-	test("builds a secure ASR URL with a session id", () => {
-		let url: URL;
-		try {
-			url = new URL(asrEndpoint("session-123"));
-		} catch (error) {
-			throw new Error("ASR endpoint was not a valid URL", { cause: error });
-		}
-		expect(url.protocol).toBe("wss:");
-		expect(url.hostname).toBe("shortwave.facebook.com");
-		expect(url.searchParams.get("sessionId")).toBe("session-123");
-	});
-
-	test("ships the macOS helper resources", () => {
-		const root = join(
-			dirname(fileURLToPath(import.meta.url)),
-			"../extensions/voice",
-		);
-		for (const file of [
-			"macos-audio.swift",
-			"Info.plist",
-			"Entitlements.plist",
-		]) {
-			expect(existsSync(join(root, file))).toBe(true);
-		}
-	});
-});

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "allowImportingTsExtensions": true,
-    "skipLibCheck": true,
-    "types": ["bun-types"]
-  },
-  "include": ["extensions", "tests"]
-}