@cartridge/controller 0.13.5 → 0.13.7

package/.turbo/turbo-build$colon$deps.log

@@ -1,16 +1,26 @@
 
-> @cartridge/controller@0.13.5 build:deps /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build:deps /home/runner/work/controller/controller/packages/controller
 > pnpm build
 
 
-> @cartridge/controller@0.13.5 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.5 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build:browser /home/runner/work/controller/controller/packages/controller
 > vite build
 
 vite v6.3.4 building for production...
+src/lookup.ts:116:7 - error TS2322: Type 'string[]' is not assignable to type '("base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password")[]'.
+  Type 'string' is not assignable to type '"base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
+
+116 const HEADLESS_AUTH_OPTIONS: AuthOption[] = [
+          ~~~~~~~~~~~~~~~~~~~~~
+src/lookup.ts:125:56 - error TS2345: Argument of type 'string' is not assignable to parameter of type '"metamask" | "rabby" | "phantom-evm" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
+
+125 ].filter((option) => IMPLEMENTED_AUTH_OPTIONS.includes(option));
+                                                           ~~~~~~
+
 transforming...
 ../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Address.js (6:21): A comment
 
@@ -40,14 +50,14 @@ rendering chunks...
 
 [vite:dts] Start generate declaration files...
 computing gzip size...
-dist/session.js             10.19 kB │ gzip:  3.09 kB │ map:  23.94 kB
-dist/provider-NKp7_oNj.js   15.63 kB │ gzip:  6.32 kB │ map:  41.81 kB
-dist/index.js              208.69 kB │ gzip: 55.04 kB │ map: 607.52 kB
-[vite:dts] Declaration files built in 3567ms.
+dist/session.js          10.53 kB │ gzip:  3.24 kB │ map:  25.46 kB
+dist/index-CYAUAqql.js   38.34 kB │ gzip: 12.80 kB │ map:  81.12 kB
+dist/index.js           188.96 kB │ gzip: 49.77 kB │ map: 576.04 kB
+[vite:dts] Declaration files built in 3626ms.
 
-✓ built in 5.63s
+✓ built in 5.76s
 
-> @cartridge/controller@0.13.5 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build:node /home/runner/work/controller/controller/packages/controller
 > tsup --config tsup.node.config.ts
 
 CLI Building entry: src/node/index.ts
@@ -58,15 +68,15 @@ computing gzip size...
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
+"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
 Entry module "dist/node/index.cjs" is using named and default exports together. Consumers of your bundle will have to use `chunk.default` to access the default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
-ESM dist/node/index.js     23.43 KB
-ESM dist/node/index.js.map 55.93 KB
-ESM ⚡️ Build success in 320ms
-CJS dist/node/index.cjs     24.32 KB
-CJS dist/node/index.cjs.map 56.16 KB
-CJS ⚡️ Build success in 320ms
+"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
+CJS dist/node/index.cjs     24.40 KB
+CJS dist/node/index.cjs.map 56.82 KB
+CJS ⚡️ Build success in 326ms
+ESM dist/node/index.js     23.50 KB
+ESM dist/node/index.js.map 56.57 KB
+ESM ⚡️ Build success in 326ms
 DTS Build start
 DTS ⚡️ Build success in 3096ms
 DTS dist/node/index.d.ts  6.42 KB

package/.turbo/turbo-build.log

@@ -1,12 +1,22 @@
 
-> @cartridge/controller@0.13.5 build /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build /home/runner/work/controller/controller/packages/controller
 > pnpm build:browser && pnpm build:node
 
 
-> @cartridge/controller@0.13.5 build:browser /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build:browser /home/runner/work/controller/controller/packages/controller
 > vite build
 
 vite v6.3.4 building for production...
+src/lookup.ts:116:7 - error TS2322: Type 'string[]' is not assignable to type '("base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password")[]'.
+  Type 'string' is not assignable to type '"base" | "metamask" | "rabby" | "phantom-evm" | "argent" | "braavos" | "phantom" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
+
+116 const HEADLESS_AUTH_OPTIONS: AuthOption[] = [
+          ~~~~~~~~~~~~~~~~~~~~~
+src/lookup.ts:125:56 - error TS2345: Argument of type 'string' is not assignable to parameter of type '"metamask" | "rabby" | "phantom-evm" | "google" | "webauthn" | "discord" | "walletconnect" | "password"'.
+
+125 ].filter((option) => IMPLEMENTED_AUTH_OPTIONS.includes(option));
+                                                           ~~~~~~
+
 transforming...
 ../../node_modules/.pnpm/ox@0.4.4_typescript@5.8.3_zod@3.24.4/node_modules/ox/_esm/core/Address.js (6:21): A comment
 
@@ -36,14 +46,14 @@ rendering chunks...
 
 [vite:dts] Start generate declaration files...
 computing gzip size...
-dist/session.js             10.19 kB │ gzip:  3.09 kB │ map:  23.94 kB
-dist/provider-NKp7_oNj.js   15.63 kB │ gzip:  6.32 kB │ map:  41.81 kB
-dist/index.js              208.69 kB │ gzip: 55.04 kB │ map: 607.52 kB
-[vite:dts] Declaration files built in 3532ms.
+dist/session.js          10.53 kB │ gzip:  3.24 kB │ map:  25.46 kB
+dist/index-CYAUAqql.js   38.34 kB │ gzip: 12.80 kB │ map:  81.12 kB
+dist/index.js           188.96 kB │ gzip: 49.77 kB │ map: 576.04 kB
+[vite:dts] Declaration files built in 3619ms.
 
-✓ built in 5.65s
+✓ built in 5.80s
 
-> @cartridge/controller@0.13.5 build:node /home/runner/work/controller/controller/packages/controller
+> @cartridge/controller@0.13.7 build:node /home/runner/work/controller/controller/packages/controller
 > tsup --config tsup.node.config.ts
 
 CLI Building entry: src/node/index.ts
@@ -54,16 +64,16 @@ computing gzip size...
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
+"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
+"constants" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.cjs".
 Entry module "dist/node/index.cjs" is using named and default exports together. Consumers of your bundle will have to use `chunk.default` to access the default export, which may not be what you want. Use `output.exports: "named"` to disable this warning.
-"constants", "getChecksumAddress" and "shortString" are imported from external module "starknet" but never used in "dist/node/index.js".
-ESM dist/node/index.js     23.43 KB
-ESM dist/node/index.js.map 55.93 KB
+ESM dist/node/index.js     23.50 KB
+ESM dist/node/index.js.map 56.57 KB
 ESM ⚡️ Build success in 289ms
-CJS dist/node/index.cjs     24.32 KB
-CJS dist/node/index.cjs.map 56.16 KB
+CJS dist/node/index.cjs     24.40 KB
+CJS dist/node/index.cjs.map 56.82 KB
 CJS ⚡️ Build success in 289ms
 DTS Build start
-DTS ⚡️ Build success in 3292ms
+DTS ⚡️ Build success in 3087ms
 DTS dist/node/index.d.ts  6.42 KB
 DTS dist/node/index.d.cts 6.42 KB

package/HEADLESS_MODE.md

@@ -2,13 +2,16 @@
 
 ## Overview
 
-Headless mode enables programmatic authentication with the Cartridge Controller SDK without displaying any UI. You trigger headless mode by passing a `username` and `signer` to `connect(...)`.
+Headless mode enables programmatic authentication with the Cartridge Controller
+SDK without displaying any UI. You trigger headless mode by passing a `username`
+and `signer` to `connect(...)`.
 
 ```
 Controller SDK → Keychain iframe (hidden) → Backend API
 ```
 
 **Key Points**
+
 - The keychain iframe still exists, but the modal is not opened.
 - The SDK passes the connect request to keychain over Penpal.
 - Keychain executes the same authentication logic as the UI flow.
@@ -16,6 +19,20 @@ Controller SDK → Keychain iframe (hidden) → Backend API
 
 ## Usage
 
+### Username Lookup (Recommended)
+
+Use lookup first so your app can decide whether to login or signup and show the
+available signer methods for existing accounts.
+
+```ts
+const lookup = await controller.lookupUsername("alice");
+
+if (lookup.exists) {
+  // e.g. ["webauthn", "google", "password"]
+  console.log(lookup.signers);
+}
+```
+
 ### Basic (Passkey / WebAuthn)
 
 ```ts
@@ -31,6 +48,9 @@ await controller.connect({
 });
 ```
 
+If `alice` does not exist yet, headless connect will create a new account and
+continue.
+
 ### Password
 
 ```ts
@@ -60,6 +80,7 @@ await controller.connect({ username: "alice", signer: "walletconnect" });
 ## Supported Auth Options
 
 Headless mode supports all **implemented** auth options:
+
 - `webauthn`
 - `password`
 - `google`
@@ -72,8 +93,8 @@ Headless mode supports all **implemented** auth options:
 ## Handling Session Approval
 
 If policies are unverified or include approvals, Keychain will prompt for
-session approval **after** authentication. In that case, `connect` will open
-the approval UI and resolve once the session is approved.
+session approval **after** authentication. In that case, `connect` will open the
+approval UI and resolve once the session is approved.
 
 ```ts
 const account = await controller.connect({
@@ -83,6 +104,7 @@ const account = await controller.connect({
 
 console.log("Session approved:", account.address);
 ```
+
 If you want to react to connection state changes, subscribe to the standard
 wallet events (for example `accountsChanged`) or just await `connect(...)` and
 update your app state afterwards.
@@ -92,9 +114,7 @@ update your app state afterwards.
 The SDK provides specific error classes for headless mode:
 
 ```ts
-import {
-  HeadlessAuthenticationError,
-} from "@cartridge/controller";
+import { HeadlessAuthenticationError } from "@cartridge/controller";
 
 try {
   await controller.connect({ username: "alice", signer: "webauthn" });
@@ -107,7 +127,8 @@ try {
 
 ## Notes
 
-- Headless mode uses the **existing signers** on the controller for the given username.
+- Headless mode can create new accounts when the username does not exist.
+- For existing accounts, the requested signer must already be registered.
 - For passkeys, the account must already have a WebAuthn signer registered.
 - If policies are unverified or include approvals, Keychain will request
   explicit approval after authentication.

package/dist/controller.d.ts

@@ -3,7 +3,7 @@ import { WalletWithStarknetFeatures } from '@starknet-io/get-starknet-wallet-sta
 import { AddStarknetChainParameters } from '@starknet-io/types-js';
 import { WalletAccount } from 'starknet';
 import { default as BaseProvider } from './provider';
-import { AuthOptions, ConnectOptions, ControllerOptions, ProfileContextTypeVariant, OpenOptions, StarterpackOptions } from './types';
+import { AuthOptions, ConnectOptions, ControllerOptions, ProfileContextTypeVariant, OpenOptions, HeadlessUsernameLookupResult, StarterpackOptions } from './types';
 export default class ControllerProvider extends BaseProvider {
     private keychain?;
     private options;
@@ -28,6 +28,7 @@ export default class ControllerProvider extends BaseProvider {
     revoke(origin: string, _policy: Policy[]): Promise<void> | null;
     rpcUrl(): string;
     username(): Promise<string> | undefined;
+    lookupUsername(username: string): Promise<HeadlessUsernameLookupResult>;
     openPurchaseCredits(): void;
     openStarterPack(id: string | number, options?: StarterpackOptions): Promise<void>;
     openExecute(calls: any, chainId?: string): Promise<{