@sirosfoundation/wcc-types 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, SIROS Foundation
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,15 @@
+# Wallet Companion client types.
+
+Types for the Wallet Companion client API.
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/sirosfoundation/wallet-companion/issues)
+- Discussions: [GitHub Discussions](https://github.com/sirosfoundation/wallet-companion/discussions)
+- Documentation: see links above
+
+## License
+
+BSD 2-Clause License - see [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2026 - present, SIROS Foundation

package/dist/index.d.mts

@@ -0,0 +1,196 @@
+//#region src/WalletCompanionInterface.d.ts
+/**
+ * Public API for the Wallet Companion browser extension.
+ *
+ * @example
+ * ```typescript
+ * if (window.WalletCompanion?.isInstalled) {
+ *   await window.WalletCompanion.registerWallet({
+ *     name: 'My Wallet',
+ *     url: 'https://wallet.example.com',
+ *     protocols: ['openid4vp'],
+ *   });
+ * }
+ * ```
+ */
+interface WalletCompanionInterface {
+  /**
+   * Semantic version of the extension (e.g. `"1.2.3"`).
+   */
+  readonly version: string;
+  /**
+   * Always `true` when the extension is active.
+   *
+   * Since `window.WalletCompanion` is undefined when the extension is not installed,
+   * use optional chaining: `window.WalletCompanion?.isInstalled`
+   */
+  readonly isInstalled: boolean;
+  /**
+   * Protocol identifiers supported by at least one registered wallet.
+   *
+   * Use this to check if any wallet can handle a specific protocol before initiating a flow.
+   *
+   * @example
+   * ```typescript
+   * if (window.WalletCompanion?.supportedProtocols.includes('openid4vp')) {
+   *   // At least one wallet supports OpenID4VP
+   * }
+   * ```
+   */
+  readonly supportedProtocols: readonly string[];
+  /**
+   * Register a wallet with the extension.
+   *
+   * Idempotent: if the URL is already registered, returns the existing wallet.
+   *
+   * @throws {Error} If validation fails or registration times out (5s)
+   *
+   * @example
+   * ```typescript
+   * const { wallet, alreadyRegistered } = await window.WalletCompanion.registerWallet({
+   *   name: 'My Wallet',
+   *   url: 'https://wallet.example.com',
+   *   protocols: ['openid4vp'],
+   * });
+   * ```
+   */
+  registerWallet(walletInfo: WalletRegistrationInput): Promise<WalletRegistrationResult>;
+  /**
+   * Check if a wallet URL is already registered.
+   *
+   * Use this to avoid prompting users to register a wallet they've already added.
+   *
+   * @throws {Error} If check times out (5s)
+   */
+  isWalletRegistered(url: string): Promise<boolean>;
+}
+/**
+ * Input for {@link WalletCompanionInterface.registerWallet}.
+ */
+type WalletRegistrationInput = {
+  /**
+   * Display name shown in the wallet selector UI.
+   */
+  name: string;
+  /**
+   * Base URL where the wallet receives requests (e.g. `https://wallet.example.com`).
+   * Must use `http:` or `https:` scheme.
+   */
+  url: string;
+  /**
+   * URL to the wallet's icon. Fetched and converted to a data-URI during registration.
+   * Recommended: square image, at least 64x64px.
+   */
+  icon?: string | null;
+  /**
+   * Short tagline shown below the wallet name in the selector UI.
+   */
+  description?: string | null;
+  /**
+   * Brand color used for UI accents. Must be a 6-digit hex code (e.g. `#FF0000`).
+   */
+  color?: string | null;
+  /**
+   * Protocol identifiers this wallet supports (e.g. `['openid4vp']`).
+   * Only wallets matching the requested protocol are shown in the selector.
+   * Format: lowercase alphanumeric with hyphens.
+   */
+  protocols?: string[] | null;
+};
+/**
+ * Result from {@link WalletCompanionInterface.registerWallet}.
+ */
+type WalletRegistrationResult = {
+  /**
+   * `true` if the wallet is now registered (whether newly added or already existed).
+   */
+  success: boolean;
+  /**
+   * `true` if the wallet URL was already registered. The existing wallet is returned unchanged.
+   */
+  alreadyRegistered: boolean;
+  /**
+   * The registered wallet with server-generated fields populated.
+   * Only present when `success` is `true`.
+   */
+  wallet?: Wallet;
+};
+/**
+ * A wallet registered with the extension.
+ */
+type Wallet = {
+  /**
+   * Unique identifier generated by the extension. Use this to reference the wallet in API calls.
+   * Not derived from the URL—two wallets with different IDs may share the same URL across browser profiles.
+   */
+  id: string;
+  /**
+   * Display name shown in the wallet selector UI.
+   */
+  name: string;
+  /**
+   * Base URL where the wallet receives requests.
+   */
+  url: string;
+  /**
+   * Data-URI of the wallet's icon, converted from the original URL during registration.
+   * Falls back to a generated icon if none was provided.
+   */
+  icon: string;
+  /**
+   * Short tagline shown below the wallet name.
+   */
+  description?: string | null;
+  /**
+   * Brand color for UI accents (6-digit hex, e.g. `#FF0000`).
+   */
+  color?: string | null;
+  /**
+   * Protocol identifiers this wallet supports.
+   */
+  protocols?: string[] | null;
+  /**
+   * Whether the wallet is active. Disabled wallets are hidden from the selector.
+   */
+  enabled: boolean;
+  /**
+   * `true` if the wallet was registered automatically (e.g. via a website's registration prompt)
+   * rather than manually by the user.
+   */
+  autoRegistered?: boolean | null;
+  /**
+   * Origin of the page that triggered auto-registration (e.g. `https://wallet.example.com`).
+   */
+  registeredFrom?: string | null;
+  /**
+   * ISO 8601 timestamp of when the wallet was registered.
+   */
+  registeredAt?: string | null;
+};
+//#endregion
+//#region src/index.d.ts
+declare global {
+  interface Window {
+    /**
+     * Client API for the Wallet Companion browser extension.
+     *
+     * Undefined when the extension is not installed. Use optional chaining to check availability:
+     *
+     * @example
+     * ```typescript
+     * if (window.WalletCompanion?.isInstalled) {
+     *   await window.WalletCompanion.registerWallet({
+     *     name: 'My Wallet',
+     *     url: 'https://wallet.example.com',
+     *     protocols: ['openid4vp'],
+     *   });
+     * }
+     * ```
+     *
+     * @see https://github.com/sirosfoundation/wallet-companion
+     */
+    WalletCompanion?: WalletCompanionInterface;
+  }
+}
+//#endregion
+export { Wallet, WalletCompanionInterface, WalletRegistrationInput, WalletRegistrationResult };

package/dist/index.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@sirosfoundation/wcc-types",
+  "version": "0.1.0-beta.0",
+  "description": "Wallet Companion client types",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.22.2"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}