@partylayer/provider 0.2.6 → 0.3.0

package/dist/index.d.mts

@@ -97,6 +97,40 @@ interface AnnounceDiscoveryOptions {
  * Announce replies are deduped by id within a single call.
  */
 declare function discoverAnnouncedProviders(options?: AnnounceDiscoveryOptions): Promise<DiscoveredProvider[]>;
+/** Options for {@link subscribeAnnouncedProviders}. */
+interface AnnounceSubscribeOptions {
+    /** Build a CIP-0103 provider from an announce. Defaults to the channel provider. */
+    createProvider?: (announced: AnnouncedWallet) => CIP0103Provider | Promise<CIP0103Provider>;
+    /** Dispatch `canton:requestProvider` on subscribe to elicit replies (default true). */
+    requestOnSubscribe?: boolean;
+}
+/**
+ * PERSISTENT (EIP-6963-style) announce subscription. Mounts a `window` listener
+ * for `canton:announceProvider` that stays up until the returned unsubscribe runs.
+ * Unlike {@link discoverAnnouncedProviders} (a one-shot snapshot that stops
+ * listening after `timeoutMs`), this captures announces that arrive AT ANY TIME —
+ * both LATE (slow/late extension injection, after the request window) and announces
+ * fired on inject BEFORE this subscription. Dispatches `canton:requestProvider`
+ * once on subscribe (unless disabled) to elicit replies. Calls `onProvider` once
+ * per newly-announced id (deduped) whose provider builds + passes the CIP-0103
+ * shape check.
+ *
+ * The caller MUST call the returned unsubscribe to remove the listener (no leak).
+ */
+declare function subscribeAnnouncedProviders(onProvider: (provider: DiscoveredProvider) => void, options?: AnnounceSubscribeOptions): () => void;
+/** Options for {@link waitForAnnouncedProvider}. */
+interface WaitForAnnouncedOptions extends AnnounceSubscribeOptions {
+    /** Max wait before resolving null (default 3000ms). Resolves EARLY on a match. */
+    timeoutMs?: number;
+}
+/**
+ * Resolve the FIRST announced provider matching `predicate` the MOMENT it arrives,
+ * or `null` after `timeoutMs`. Built on {@link subscribeAnnouncedProviders}, so a
+ * LATE announce within the bound is captured (vs a fixed window that returns its
+ * snapshot at a fixed time and misses anything later). Auto-unsubscribes on
+ * resolve/timeout — no lingering listener.
+ */
+declare function waitForAnnouncedProvider(predicate: (provider: DiscoveredProvider) => boolean, options?: WaitForAnnouncedOptions): Promise<DiscoveredProvider | null>;
 /**
  * Discover ALL CIP-0103 wallets: the synchronous `window.canton` scan PLUS the
  * `canton:announceProvider` handshake, MERGED and deduped by stable provider id.
@@ -455,4 +489,4 @@ declare class MethodRouter {
     private registerDefaults;
 }
 
-export { type AnnounceDiscoveryOptions, type AnnouncedWallet, type AsyncConnectOptions, type AsyncPrepareExecuteOptions, type BridgeableClient, CIP0103EventBus, type DiscoveredProvider, type ExtensionChannelOptions, JSON_RPC_ERRORS, type MethodHandler, MethodRouter, PartyLayerProvider, type PartyLayerProviderOptions, ProviderRpcError, RPC_ERRORS, chainDisconnected, createExtensionChannelProvider, createProviderBridge, disconnected, discoverAnnouncedProviders, discoverInjectedProviders, discoverProviders, handleAsyncConnect, handleAsyncPrepareExecute, internalError, invalidParams, isCIP0103Provider, methodNotFound, resourceNotFound, resourceUnavailable, toPartyLayerError, toProviderRpcError, transactionRejected, unauthorized, unsupportedMethod, userRejected, waitForProvider };
+export { type AnnounceDiscoveryOptions, type AnnounceSubscribeOptions, type AnnouncedWallet, type AsyncConnectOptions, type AsyncPrepareExecuteOptions, type BridgeableClient, CIP0103EventBus, type DiscoveredProvider, type ExtensionChannelOptions, JSON_RPC_ERRORS, type MethodHandler, MethodRouter, PartyLayerProvider, type PartyLayerProviderOptions, ProviderRpcError, RPC_ERRORS, type WaitForAnnouncedOptions, chainDisconnected, createExtensionChannelProvider, createProviderBridge, disconnected, discoverAnnouncedProviders, discoverInjectedProviders, discoverProviders, handleAsyncConnect, handleAsyncPrepareExecute, internalError, invalidParams, isCIP0103Provider, methodNotFound, resourceNotFound, resourceUnavailable, subscribeAnnouncedProviders, toPartyLayerError, toProviderRpcError, transactionRejected, unauthorized, unsupportedMethod, userRejected, waitForAnnouncedProvider, waitForProvider };

package/dist/index.d.ts

@@ -97,6 +97,40 @@ interface AnnounceDiscoveryOptions {
  * Announce replies are deduped by id within a single call.
  */
 declare function discoverAnnouncedProviders(options?: AnnounceDiscoveryOptions): Promise<DiscoveredProvider[]>;
+/** Options for {@link subscribeAnnouncedProviders}. */
+interface AnnounceSubscribeOptions {
+    /** Build a CIP-0103 provider from an announce. Defaults to the channel provider. */
+    createProvider?: (announced: AnnouncedWallet) => CIP0103Provider | Promise<CIP0103Provider>;
+    /** Dispatch `canton:requestProvider` on subscribe to elicit replies (default true). */
+    requestOnSubscribe?: boolean;
+}
+/**
+ * PERSISTENT (EIP-6963-style) announce subscription. Mounts a `window` listener
+ * for `canton:announceProvider` that stays up until the returned unsubscribe runs.
+ * Unlike {@link discoverAnnouncedProviders} (a one-shot snapshot that stops
+ * listening after `timeoutMs`), this captures announces that arrive AT ANY TIME —
+ * both LATE (slow/late extension injection, after the request window) and announces
+ * fired on inject BEFORE this subscription. Dispatches `canton:requestProvider`
+ * once on subscribe (unless disabled) to elicit replies. Calls `onProvider` once
+ * per newly-announced id (deduped) whose provider builds + passes the CIP-0103
+ * shape check.
+ *
+ * The caller MUST call the returned unsubscribe to remove the listener (no leak).
+ */
+declare function subscribeAnnouncedProviders(onProvider: (provider: DiscoveredProvider) => void, options?: AnnounceSubscribeOptions): () => void;
+/** Options for {@link waitForAnnouncedProvider}. */
+interface WaitForAnnouncedOptions extends AnnounceSubscribeOptions {
+    /** Max wait before resolving null (default 3000ms). Resolves EARLY on a match. */
+    timeoutMs?: number;
+}
+/**
+ * Resolve the FIRST announced provider matching `predicate` the MOMENT it arrives,
+ * or `null` after `timeoutMs`. Built on {@link subscribeAnnouncedProviders}, so a
+ * LATE announce within the bound is captured (vs a fixed window that returns its
+ * snapshot at a fixed time and misses anything later). Auto-unsubscribes on
+ * resolve/timeout — no lingering listener.
+ */
+declare function waitForAnnouncedProvider(predicate: (provider: DiscoveredProvider) => boolean, options?: WaitForAnnouncedOptions): Promise<DiscoveredProvider | null>;
 /**
  * Discover ALL CIP-0103 wallets: the synchronous `window.canton` scan PLUS the
  * `canton:announceProvider` handshake, MERGED and deduped by stable provider id.
@@ -455,4 +489,4 @@ declare class MethodRouter {
     private registerDefaults;
 }
 
-export { type AnnounceDiscoveryOptions, type AnnouncedWallet, type AsyncConnectOptions, type AsyncPrepareExecuteOptions, type BridgeableClient, CIP0103EventBus, type DiscoveredProvider, type ExtensionChannelOptions, JSON_RPC_ERRORS, type MethodHandler, MethodRouter, PartyLayerProvider, type PartyLayerProviderOptions, ProviderRpcError, RPC_ERRORS, chainDisconnected, createExtensionChannelProvider, createProviderBridge, disconnected, discoverAnnouncedProviders, discoverInjectedProviders, discoverProviders, handleAsyncConnect, handleAsyncPrepareExecute, internalError, invalidParams, isCIP0103Provider, methodNotFound, resourceNotFound, resourceUnavailable, toPartyLayerError, toProviderRpcError, transactionRejected, unauthorized, unsupportedMethod, userRejected, waitForProvider };
+export { type AnnounceDiscoveryOptions, type AnnounceSubscribeOptions, type AnnouncedWallet, type AsyncConnectOptions, type AsyncPrepareExecuteOptions, type BridgeableClient, CIP0103EventBus, type DiscoveredProvider, type ExtensionChannelOptions, JSON_RPC_ERRORS, type MethodHandler, MethodRouter, PartyLayerProvider, type PartyLayerProviderOptions, ProviderRpcError, RPC_ERRORS, type WaitForAnnouncedOptions, chainDisconnected, createExtensionChannelProvider, createProviderBridge, disconnected, discoverAnnouncedProviders, discoverInjectedProviders, discoverProviders, handleAsyncConnect, handleAsyncPrepareExecute, internalError, invalidParams, isCIP0103Provider, methodNotFound, resourceNotFound, resourceUnavailable, subscribeAnnouncedProviders, toPartyLayerError, toProviderRpcError, transactionRejected, unauthorized, unsupportedMethod, userRejected, waitForAnnouncedProvider, waitForProvider };

package/dist/index.js

@@ -509,7 +509,7 @@ var PartyLayerProvider = class {
 };
 
 // src/bridge.ts
-var PROVIDER_VERSION = "0.2.6" ;
+var PROVIDER_VERSION = "0.3.0" ;
 function createProviderBridge(client) {
   const eventBus = new CIP0103EventBus();
   const pendingEmitted = /* @__PURE__ */ new Set();
@@ -1006,6 +1006,70 @@ async function discoverAnnouncedProviders(options = {}) {
   }
   return results;
 }
+function subscribeAnnouncedProviders(onProvider, options = {}) {
+  if (typeof window === "undefined") return () => {
+  };
+  const make = options.createProvider ?? defaultAnnounceProvider;
+  const seen = /* @__PURE__ */ new Set();
+  const onAnnounce = (event) => {
+    const detail = event.detail;
+    if (!detail) return;
+    const rawId = detail.providerId ?? detail.id;
+    if (typeof rawId !== "string" || rawId.length === 0) return;
+    if (seen.has(rawId)) return;
+    seen.add(rawId);
+    const wallet = {
+      id: rawId,
+      name: typeof detail.name === "string" ? detail.name : void 0,
+      icon: typeof detail.icon === "string" ? detail.icon : void 0,
+      target: typeof detail.target === "string" ? detail.target : void 0
+    };
+    void Promise.resolve().then(() => make(wallet)).then((provider) => {
+      if (!isCIP0103Provider(provider)) return;
+      onProvider({
+        id: wallet.id,
+        provider,
+        source: "injected",
+        name: wallet.name,
+        icon: wallet.icon
+      });
+    }).catch(() => {
+    });
+  };
+  window.addEventListener(
+    CANTON_ANNOUNCE_PROVIDER_EVENT,
+    onAnnounce
+  );
+  if (options.requestOnSubscribe !== false) {
+    window.dispatchEvent(new CustomEvent(CANTON_REQUEST_PROVIDER_EVENT));
+  }
+  return () => window.removeEventListener(
+    CANTON_ANNOUNCE_PROVIDER_EVENT,
+    onAnnounce
+  );
+}
+function waitForAnnouncedProvider(predicate, options = {}) {
+  if (typeof window === "undefined") return Promise.resolve(null);
+  const timeoutMs = options.timeoutMs ?? 3e3;
+  return new Promise((resolve) => {
+    const h = {
+      done: false,
+      unsubscribe: () => {
+      }
+    };
+    const finish = (value) => {
+      if (h.done) return;
+      h.done = true;
+      if (h.timer) clearTimeout(h.timer);
+      h.unsubscribe();
+      resolve(value);
+    };
+    h.unsubscribe = subscribeAnnouncedProviders((p) => {
+      if (predicate(p)) finish(p);
+    }, { createProvider: options.createProvider, requestOnSubscribe: options.requestOnSubscribe });
+    h.timer = setTimeout(() => finish(null), timeoutMs);
+  });
+}
 var INJECTED_ID_PROBE_TIMEOUT_MS = 1500;
 function raceTimeout(promise, ms) {
   return Promise.race([
@@ -1098,12 +1162,14 @@ exports.isCIP0103Provider = isCIP0103Provider;
 exports.methodNotFound = methodNotFound;
 exports.resourceNotFound = resourceNotFound;
 exports.resourceUnavailable = resourceUnavailable;
+exports.subscribeAnnouncedProviders = subscribeAnnouncedProviders;
 exports.toPartyLayerError = toPartyLayerError;
 exports.toProviderRpcError = toProviderRpcError;
 exports.transactionRejected = transactionRejected;
 exports.unauthorized = unauthorized;
 exports.unsupportedMethod = unsupportedMethod;
 exports.userRejected = userRejected;
+exports.waitForAnnouncedProvider = waitForAnnouncedProvider;
 exports.waitForProvider = waitForProvider;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map