archastro.platform.v1.resources.event_subscriptions

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: ee8786d0c9ca
  4
  5from __future__ import annotations
  6
  7from typing import Literal, Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import (
 11    EventSubscription,
 12    EventSubscriptionClaim,
 13    EventSubscriptionHead,
 14    EventSubscriptionPage,
 15    EventSubscriptionQueue,
 16)
 17
 18
 19class EventSubscriptionCreateInput(TypedDict, total=False):
 20    "Create a domain-event subscription"
 21
 22    event_names: Required[list[str]]
 23    "Exact event names to receive."
 24    max_pending_events: int | None
 25    "Queue cap. Defaults to 100; maximum 1000."
 26    name: Required[str]
 27    "Customer-defined subscription name."
 28    retention_seconds: int | None
 29    "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only."
 30    status: Literal["active", "paused"] | None
 31    "Initial status. Defaults to active."
 32    visibility_timeout_seconds: int | None
 33    "Default claim lease in seconds. Defaults to 300."
 34
 35
 36class EventSubscriptionUpdateInput(TypedDict, total=False):
 37    "Update a domain-event subscription"
 38
 39    event_names: list[str] | None
 40    max_pending_events: int | None
 41    name: str | None
 42    retention_seconds: int | None
 43    "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only."
 44    status: Literal["active", "paused"] | None
 45    visibility_timeout_seconds: int | None
 46
 47
 48class EventSubscriptionClaimInput(TypedDict, total=False):
 49    "Claim events from a subscription"
 50
 51    consumer_id: str | None
 52    "Consumer identity between 1 and 128 bytes, recorded on the lease for attribution."
 53    max_events: int | None
 54    "Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics."
 55    request_id: str | None
 56    "Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases."
 57    visibility_timeout_seconds: int | None
 58    "Lease duration override between 15 and 3600 seconds."
 59    wait_seconds: int | None
 60    "Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately."
 61
 62
 63class AsyncEventSubscriptionResource:
 64    def __init__(self, http: HttpClient):
 65        self._http = http
 66
 67    async def list(
 68        self, *, page: int | None = None, per_page: int | None = None
 69    ) -> EventSubscriptionPage:
 70        """
 71        List domain-event subscriptions
 72        Lists the subscriptions visible to the caller, with current queue counters.
 73
 74        Args:
 75            page: Page number, starting at 1.
 76            per_page: Subscriptions per page, from 1 through 100.
 77
 78        Returns:
 79            Subscriptions visible to this caller.
 80        """
 81        query: dict[str, object] = {}
 82        if page is not None:
 83            query["page"] = page
 84        if per_page is not None:
 85            query["per_page"] = per_page
 86        return await self._http.request(
 87            "/api/v1/event_subscriptions",
 88            query=query,
 89            response_type=EventSubscriptionPage,
 90        )
 91
 92    async def create(self, input: EventSubscriptionCreateInput) -> EventSubscription:
 93        """
 94        Create a domain-event subscription
 95        Creates a durable subscription that receives exportable domain events matching its exact event names. Matching events fan out into a per-subscription queue bounded by max_pending_events and retention_seconds; consume with claim and acknowledge.
 96
 97        Args:
 98            input: Request body.
 99            input.event_names: Exact event names to receive.
100            input.max_pending_events: Queue cap. Defaults to 100; maximum 1000.
101            input.name: Customer-defined subscription name.
102            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
103            input.status: Initial status. Defaults to active.
104            input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300.
105
106        Returns:
107            The new volatile subscription.
108        """
109        return await self._http.request(
110            "/api/v1/event_subscriptions",
111            method="POST",
112            body=input,
113            response_type=EventSubscription,
114        )
115
116    async def delete(self, subscription: str) -> None:
117        """
118        Delete a domain-event subscription
119        Deletes the subscription and every delivery still in its queue.
120
121        Args:
122            subscription: Subscription ID (`esub_...`).
123
124        Returns:
125            No content
126        """
127        await self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE")
128
129    async def get(self, subscription: str) -> EventSubscription:
130        """
131        Get a domain-event subscription
132        Returns one subscription and its current queue counters.
133
134        Args:
135            subscription: Subscription ID (`esub_...`).
136
137        Returns:
138            Successful response
139        """
140        return await self._http.request(
141            f"/api/v1/event_subscriptions/{subscription}",
142            response_type=EventSubscription,
143        )
144
145    async def update(
146        self, subscription: str, input: EventSubscriptionUpdateInput
147    ) -> EventSubscription:
148        """
149        Update a domain-event subscription
150        Updates matching, status, or queue limits for future fanout. Already queued deliveries remain unless a lower cap trims the oldest entries; retention changes apply to future deliveries only.
151
152        Args:
153            subscription: Subscription ID (`esub_...`).
154            input: Request body.
155            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
156
157        Returns:
158            Successful response
159        """
160        return await self._http.request(
161            f"/api/v1/event_subscriptions/{subscription}",
162            method="PATCH",
163            body=input,
164            response_type=EventSubscription,
165        )
166
167    async def claim(
168        self, subscription: str, input: EventSubscriptionClaimInput
169    ) -> EventSubscriptionClaim:
170        """
171        Claim events from a subscription
172        Atomically leases the oldest unacknowledged delivery. Returns an empty data array when the queue is empty or its head already has an active lease. Passing max_events opts into batch mode, where leased entries are skipped instead of blocking; wait_seconds bounds a long poll on an empty queue.
173
174        Args:
175            subscription: Subscription ID (`esub_...`).
176            input: Request body.
177            input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution.
178            input.max_events: Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics.
179            input.request_id: Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases.
180            input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds.
181            input.wait_seconds: Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately.
182
183        Returns:
184            Successful response
185        """
186        return await self._http.request(
187            f"/api/v1/event_subscriptions/{subscription}/claim",
188            method="POST",
189            body=input,
190            response_type=EventSubscriptionClaim,
191        )
192
193    async def head(self, subscription: str) -> EventSubscriptionHead:
194        """
195        Peek at the head of a subscription queue
196        Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim.
197
198        Args:
199            subscription: Subscription ID (`esub_...`).
200
201        Returns:
202            Successful response
203        """
204        return await self._http.request(
205            f"/api/v1/event_subscriptions/{subscription}/head",
206            response_type=EventSubscriptionHead,
207        )
208
209    async def queue(
210        self,
211        subscription: str,
212        *,
213        limit: int | None = None,
214        before_cursor: str | None = None,
215        after_cursor: str | None = None,
216    ) -> EventSubscriptionQueue:
217        """
218        Read a subscription queue
219        Returns a non-reserving, oldest-first view of unacknowledged deliveries, including the queue's loss indicators (queue_epoch, dropped_events_total, dropped_through_position). Use claim to obtain a receipt handle before acknowledging.
220
221        Args:
222            subscription: Subscription ID (`esub_...`).
223            limit: Maximum entries to return, from 1 through 100.
224            before_cursor: Opaque cursor for the preceding page.
225            after_cursor: Opaque cursor for the following page.
226
227        Returns:
228            Successful response
229        """
230        query: dict[str, object] = {}
231        if limit is not None:
232            query["limit"] = limit
233        if before_cursor is not None:
234            query["before_cursor"] = before_cursor
235        if after_cursor is not None:
236            query["after_cursor"] = after_cursor
237        return await self._http.request(
238            f"/api/v1/event_subscriptions/{subscription}/queue",
239            query=query,
240            response_type=EventSubscriptionQueue,
241        )
242
243
244class EventSubscriptionResource:
245    def __init__(self, http: SyncHttpClient):
246        self._http = http
247
248    def list(
249        self, *, page: int | None = None, per_page: int | None = None
250    ) -> EventSubscriptionPage:
251        """
252        List domain-event subscriptions
253        Lists the subscriptions visible to the caller, with current queue counters.
254
255        Args:
256            page: Page number, starting at 1.
257            per_page: Subscriptions per page, from 1 through 100.
258
259        Returns:
260            Subscriptions visible to this caller.
261        """
262        query: dict[str, object] = {}
263        if page is not None:
264            query["page"] = page
265        if per_page is not None:
266            query["per_page"] = per_page
267        return self._http.request(
268            "/api/v1/event_subscriptions",
269            query=query,
270            response_type=EventSubscriptionPage,
271        )
272
273    def create(self, input: EventSubscriptionCreateInput) -> EventSubscription:
274        """
275        Create a domain-event subscription
276        Creates a durable subscription that receives exportable domain events matching its exact event names. Matching events fan out into a per-subscription queue bounded by max_pending_events and retention_seconds; consume with claim and acknowledge.
277
278        Args:
279            input: Request body.
280            input.event_names: Exact event names to receive.
281            input.max_pending_events: Queue cap. Defaults to 100; maximum 1000.
282            input.name: Customer-defined subscription name.
283            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
284            input.status: Initial status. Defaults to active.
285            input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300.
286
287        Returns:
288            The new volatile subscription.
289        """
290        return self._http.request(
291            "/api/v1/event_subscriptions",
292            method="POST",
293            body=input,
294            response_type=EventSubscription,
295        )
296
297    def delete(self, subscription: str) -> None:
298        """
299        Delete a domain-event subscription
300        Deletes the subscription and every delivery still in its queue.
301
302        Args:
303            subscription: Subscription ID (`esub_...`).
304
305        Returns:
306            No content
307        """
308        self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE")
309
310    def get(self, subscription: str) -> EventSubscription:
311        """
312        Get a domain-event subscription
313        Returns one subscription and its current queue counters.
314
315        Args:
316            subscription: Subscription ID (`esub_...`).
317
318        Returns:
319            Successful response
320        """
321        return self._http.request(
322            f"/api/v1/event_subscriptions/{subscription}",
323            response_type=EventSubscription,
324        )
325
326    def update(self, subscription: str, input: EventSubscriptionUpdateInput) -> EventSubscription:
327        """
328        Update a domain-event subscription
329        Updates matching, status, or queue limits for future fanout. Already queued deliveries remain unless a lower cap trims the oldest entries; retention changes apply to future deliveries only.
330
331        Args:
332            subscription: Subscription ID (`esub_...`).
333            input: Request body.
334            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
335
336        Returns:
337            Successful response
338        """
339        return self._http.request(
340            f"/api/v1/event_subscriptions/{subscription}",
341            method="PATCH",
342            body=input,
343            response_type=EventSubscription,
344        )
345
346    def claim(
347        self, subscription: str, input: EventSubscriptionClaimInput
348    ) -> EventSubscriptionClaim:
349        """
350        Claim events from a subscription
351        Atomically leases the oldest unacknowledged delivery. Returns an empty data array when the queue is empty or its head already has an active lease. Passing max_events opts into batch mode, where leased entries are skipped instead of blocking; wait_seconds bounds a long poll on an empty queue.
352
353        Args:
354            subscription: Subscription ID (`esub_...`).
355            input: Request body.
356            input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution.
357            input.max_events: Opts into batch mode: leases up to this many lease-available deliveries (between 1 and 20) in sequence order, skipping leased entries instead of blocking on the head. Omit to keep strict head-of-line semantics.
358            input.request_id: Idempotency key between 1 and 128 bytes. Use a value unique per claim attempt (e.g. a UUID) the key is scoped to the subscription, so a reused value takes over whatever leases it last stamped. Retrying a claim with the same request_id while its leases are unexpired returns the same deliveries (regardless of max_events) with fresh receipt handles and refreshed leases.
359            input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds.
360            input.wait_seconds: Long-poll bound between 0 and 20 seconds. When the queue is empty, the request waits up to this long for a delivery before returning an empty data array. 0 (or omitting) returns immediately.
361
362        Returns:
363            Successful response
364        """
365        return self._http.request(
366            f"/api/v1/event_subscriptions/{subscription}/claim",
367            method="POST",
368            body=input,
369            response_type=EventSubscriptionClaim,
370        )
371
372    def head(self, subscription: str) -> EventSubscriptionHead:
373        """
374        Peek at the head of a subscription queue
375        Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim.
376
377        Args:
378            subscription: Subscription ID (`esub_...`).
379
380        Returns:
381            Successful response
382        """
383        return self._http.request(
384            f"/api/v1/event_subscriptions/{subscription}/head",
385            response_type=EventSubscriptionHead,
386        )
387
388    def queue(
389        self,
390        subscription: str,
391        *,
392        limit: int | None = None,
393        before_cursor: str | None = None,
394        after_cursor: str | None = None,
395    ) -> EventSubscriptionQueue:
396        """
397        Read a subscription queue
398        Returns a non-reserving, oldest-first view of unacknowledged deliveries, including the queue's loss indicators (queue_epoch, dropped_events_total, dropped_through_position). Use claim to obtain a receipt handle before acknowledging.
399
400        Args:
401            subscription: Subscription ID (`esub_...`).
402            limit: Maximum entries to return, from 1 through 100.
403            before_cursor: Opaque cursor for the preceding page.
404            after_cursor: Opaque cursor for the following page.
405
406        Returns:
407            Successful response
408        """
409        query: dict[str, object] = {}
410        if limit is not None:
411            query["limit"] = limit
412        if before_cursor is not None:
413            query["before_cursor"] = before_cursor
414        if after_cursor is not None:
415            query["after_cursor"] = after_cursor
416        return self._http.request(
417            f"/api/v1/event_subscriptions/{subscription}/queue",
418            query=query,
419            response_type=EventSubscriptionQueue,
420        )