API client for interacting with the Virtufin Gateway service. Provides service discovery, method invocation, and event subscription capabilities.

Constructors

Methods

  • Aborts all shared reply-topic readers. Call when the client is no longer needed; pending publishWithResult callers will time out.

    Returns void

  • Deletes many keys in one round trip. On partial failure status.success is false and failedKeys names the keys that survived -- retry those rather than the whole batch.

    Parameters

    • service: string
    • keys: string[]
    • publishChange: boolean = false
    • Optionalchange: ChangeNotification

    Returns Promise<DeleteBulkStateResponse>

  • Deletes one state value. Check status.success.

    Parameters

    • service: string
    • key: string
    • Optionalopts: {
          change?: ChangeNotification;
          etag?: string;
          includeValue?: boolean;
          publishChange?: boolean;
      }

    Returns Promise<DeleteStateResponse>

  • Deletes a scheduled trigger.

    Parameters

    • name: string

    Returns Promise<DeleteTriggerResponse>

  • Reads many keys in one round trip.

    Parameters

    • service: string
    • keys: string[]

    Returns Promise<GetBulkStateResponse>

  • Gets one service's configuration. Throws with NotFound if unregistered.

    Parameters

    • name: string

    Returns Promise<GetConfigServiceResponse>

  • Gets the schema for a specific method.

    Parameters

    • service: string

      The name of the service.

    • method: string

      The name of the method.

    • type: string

      The type of schema to retrieve (e.g., "request" or "response").

    Returns Promise<GetMethodSchemaResponse>

    A promise resolving to the GetMethodSchemaResponse.

  • Reads one state value. Throws with NotFound if the key does not exist.

    Parameters

    • service: string
    • key: string

    Returns Promise<GetStateResponse>

  • Retrieves a scheduled trigger's details.

    Parameters

    • name: string

    Returns Promise<GetTriggerResponse>

  • Invokes a method on a backend service using raw protobuf bytes.

    Parameters

    • service: string

      The name of the target service.

    • method: string

      The name of the method to invoke.

    • requestData: Uint8Array

      The serialized protobuf request data as Uint8Array.

    Returns Promise<InvokeResponse>

    A promise resolving to the InvokeResponse.

  • Invokes a method on a backend service using JSON request/response data. This is the recommended method for most use cases.

    Parameters

    • service: string

      The name of the target service.

    • method: string

      The name of the method to invoke.

    • requestData: string

      The JSON serialized request data as string.

    Returns Promise<InvokeJsonResponse>

    A promise resolving to the InvokeJsonResponse.

  • Lists every registered service, including non-dialable entries (those that exist only to resolve Dapr component names). Contrast listServices, which returns only the backends the gateway can invoke.

    Returns Promise<ListConfigServicesResponse>

  • Lists all methods available for a specific service.

    Parameters

    • service: string

      The name of the service to query.

    Returns Promise<ListMethodsResponse>

    A promise resolving to the ListMethodsResponse containing method information.

  • Lists all available services registered with the gateway.

    Returns Promise<ListServicesResponse>

    A promise resolving to the ListServicesResponse containing service names.

  • Lists the topics seen at the gateway (published to or subscribed to), sorted by name, with when each was last seen. Topics unseen for 7 days drop out.

    Returns Promise<ListTopicsResponse>

  • Lists the scheduled triggers: all, or only those owned by ownerWorkerId when given.

    Parameters

    • OptionalownerWorkerId: string

    Returns Promise<ListTriggersResponse>

  • Publishes a CloudEvent to a topic via the Pubsub service.

    Parameters

    • topic: string

      The topic name.

    • cloudevent: CloudEvent

      The CloudEvent message to publish.

    Returns Promise<PublishResponse>

    A promise resolving to the PublishResponse.

  • Publishes several events in one call: each topic's events in the given order, different topics in parallel. At most 1000 events; an invalid event rejects the whole call (InvalidArgument) before anything is published.

    Parameters

    • events: { cloudevent: CloudEvent; topic: string }[]

      The events, each with its topic.

    Returns Promise<PublishEventsResponse>

    The count published and the indexes of the events that failed.

  • Publishes to a topic and waits for a correlated response on a reply topic. Implements the request-reply pattern over pub/sub using correlation IDs, via the shared per-reply-topic reader started by ensureReplyReader (see its documentation for why the stream is shared rather than per call).

    Parameters

    • topic: string

      The topic to publish the request to. *

    • cloudevent: CloudEvent

      The CloudEvent message to publish. *

    • replyTopic: string

      The topic to listen for responses on. *

    • Optionalopts: { correlationId?: string; timeout?: number }

      Options: timeout (ms, default 30000), correlationId. *

    Returns Promise<SubscribeResponse>

    A promise resolving to the matching SubscribeResponse. *

    TimeoutError if no response arrives within the timeout.

  • Queries state with Dapr's query-state DSL, e.g. {"filter":{}}. Values are stored as text, so filters cannot match fields inside a value: query everything and filter by key.

    Requires a store whose Dapr component implements the Query API; for Redis/Valkey that means RediSearch plus queryIndexes metadata. Without it every query fails, including Dapr's {} match-everything query -- use getBulkState against known keys instead.

    Parameters

    • service: string
    • query: string
    • limit: number = 0

    Returns Promise<QueryStateResponse>

  • Saves a state value. value must be valid JSON.

    Note the split error channel: validation failures throw, while a runtime failure comes back with a gRPC status of OK and status.success === false. Check status.success -- a client that only catches thrown errors will read a failed save as a success.

    With publishChange, a change notification is published after the write. By default that is the Tier 0 sys.api.state.saved/deleted topic, which is right for infra state. For domain state (positions, portfolios, orders) pass change with both a topic and a cloudevent: the API publishes your event verbatim to your topic and skips the Tier 0 topic. It cannot build that event itself -- it has the key and the bytes but not the scenario, world markers, clock type or your service identity.

    Tier 0 events carry no version, so a subscriber consuming value without a read-back is assuming writes to that key are serialized. Carry a monotonic token in your own event if you need ordering. Publication is at-most-once and not atomic with the write.

    Parameters

    • service: string
    • key: string
    • value: string
    • Optionalopts: {
          change?: ChangeNotification;
          createOnly?: boolean;
          etag?: string;
          includeValue?: boolean;
          publishChange?: boolean;
          ttlSeconds?: number;
      }
      • Optionalchange?: ChangeNotification

        Publish a domain (Tier 1) event instead of the default sys.api.state.saved/deleted notification. Set topic and cloudevent together; see saveState docs.

      • OptionalcreateOnly?: boolean
      • Optionaletag?: string
      • OptionalincludeValue?: boolean
      • OptionalpublishChange?: boolean
      • OptionalttlSeconds?: number

    Returns Promise<SaveStateResponse>

  • Schedules a recurring trigger. When it fires, the API publishes an empty CloudEvent to targetTopic.

    Parameters

    • name: string
    • targetTopic: string
    • Optionalopts: {
          dueTime?: string;
          ownerWorkerId?: string;
          repeats?: number;
          schedule?: string;
          ttl?: string;
      }

    Returns Promise<ScheduleTriggerResponse>

  • Subscribes to one or more pub/sub topics. Resolves once the API confirms the subscription (its response headers: daprd holds the subscription), so a request published after the await cannot outrun it.

    Read the events with for await; a stream failure, or aborting options.signal, rejects the iteration. End the subscription with close() (or await using), which ends the iteration cleanly.

    Parameters

    • topics: string[]

      Topics to subscribe to. Filtering is by topic only; discriminate further on cloudevent.type. Name topics explicitly: an empty list is not "all topics" (the server defaults it to the state-change topics).

    • Optionaloptions: { signal?: AbortSignal }

      signal cancels the subscribe and, later, the stream.

    Returns Promise<Subscription>

    The live subscription, iterable once.