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: 11a031f3d19d
  4
  5from __future__ import annotations
  6
  7from typing import Any, Literal, Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.events 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    filter: dict[str, Any] | None
 25    "Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events."
 26    max_pending_events: int | None
 27    "Queue cap. Defaults to 100; maximum 1000."
 28    name: Required[str]
 29    "Customer-defined subscription name."
 30    previous_filter: dict[str, Any] | None
 31    "Expected legacy filter for atomic watch-key adoption."
 32    previous_filters: list[dict[str, Any]] | None
 33    "Additional exact historical filters accepted for atomic watch-key adoption."
 34    previous_watch_key: str | None
 35    "Optionally adopt an existing key in the exact same owner and residence when the destination is absent and its filter exactly matches previous_filter, one of previous_filters, or filter. Preserves queue identity and deliveries; mismatches reject the request without changing either queue."
 36    retention_seconds: int | None
 37    "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only."
 38    status: Literal["active", "paused"] | None
 39    "Initial status. Defaults to active."
 40    visibility_timeout_seconds: int | None
 41    "Default claim lease in seconds. Defaults to 300."
 42    watch_key: str | None
 43    "Optional durable identity within the caller owner and residence. Repeated creates replace routes and filter on that queue; omission creates a new queue regardless of name."
 44
 45
 46class EventSubscriptionUpdateInput(TypedDict, total=False):
 47    "Update a domain-event subscription"
 48
 49    event_names: list[str] | None
 50    filter: dict[str, Any] | None
 51    "Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events."
 52    max_pending_events: int | None
 53    name: str | None
 54    retention_seconds: int | None
 55    "Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only."
 56    status: Literal["active", "paused"] | None
 57    visibility_timeout_seconds: int | None
 58
 59
 60class EventSubscriptionClaimInput(TypedDict, total=False):
 61    "Claim events from a subscription"
 62
 63    consumer_id: str | None
 64    "Consumer identity between 1 and 128 bytes, recorded on the lease for attribution."
 65    max_events: int | None
 66    "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."
 67    request_id: str | None
 68    "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."
 69    visibility_timeout_seconds: int | None
 70    "Lease duration override between 15 and 3600 seconds."
 71    wait_seconds: int | None
 72    "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."
 73
 74
 75class AsyncEventSubscriptionResource:
 76    def __init__(self, http: HttpClient):
 77        self._http = http
 78
 79    async def list(
 80        self, *, page: int | None = None, per_page: int | None = None
 81    ) -> EventSubscriptionPage:
 82        """
 83        List domain-event subscriptions
 84        Lists the subscriptions visible to the caller, with current queue counters.
 85
 86        Args:
 87            page: Page number, starting at 1.
 88            per_page: Subscriptions per page, from 1 through 100.
 89
 90        Returns:
 91            Subscriptions visible to this caller.
 92        """
 93        query: dict[str, object] = {}
 94        if page is not None:
 95            query["page"] = page
 96        if per_page is not None:
 97            query["per_page"] = per_page
 98        return await self._http.request(
 99            "/api/v1/event_subscriptions",
100            query=query,
101            response_type=EventSubscriptionPage,
102        )
103
104    async def create(self, input: EventSubscriptionCreateInput) -> EventSubscription:
105        """
106        Create a domain-event subscription
107        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.
108
109        Args:
110            input: Request body.
111            input.event_names: Exact event names to receive.
112            input.filter: Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events.
113            input.max_pending_events: Queue cap. Defaults to 100; maximum 1000.
114            input.name: Customer-defined subscription name.
115            input.previous_filter: Expected legacy filter for atomic watch-key adoption.
116            input.previous_filters: Additional exact historical filters accepted for atomic watch-key adoption.
117            input.previous_watch_key: Optionally adopt an existing key in the exact same owner and residence when the destination is absent and its filter exactly matches previous_filter, one of previous_filters, or filter. Preserves queue identity and deliveries; mismatches reject the request without changing either queue.
118            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
119            input.status: Initial status. Defaults to active.
120            input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300.
121            input.watch_key: Optional durable identity within the caller owner and residence. Repeated creates replace routes and filter on that queue; omission creates a new queue regardless of name.
122
123        Returns:
124            The new volatile subscription.
125        """
126        return await self._http.request(
127            "/api/v1/event_subscriptions",
128            method="POST",
129            body=input,
130            response_type=EventSubscription,
131        )
132
133    async def delete(self, subscription: str) -> None:
134        """
135        Delete a domain-event subscription
136        Deletes the subscription and every delivery still in its queue.
137
138        Args:
139            subscription: Subscription ID (`esub_...`).
140
141        Returns:
142            No content
143        """
144        await self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE")
145
146    async def get(self, subscription: str) -> EventSubscription:
147        """
148        Get a domain-event subscription
149        Returns one subscription and its current queue counters.
150
151        Args:
152            subscription: Subscription ID (`esub_...`).
153
154        Returns:
155            Successful response
156        """
157        return await self._http.request(
158            f"/api/v1/event_subscriptions/{subscription}",
159            response_type=EventSubscription,
160        )
161
162    async def update(
163        self, subscription: str, input: EventSubscriptionUpdateInput
164    ) -> EventSubscription:
165        """
166        Update a domain-event subscription
167        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.
168
169        Args:
170            subscription: Subscription ID (`esub_...`).
171            input: Request body.
172            input.filter: Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events.
173            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
174
175        Returns:
176            Successful response
177        """
178        return await self._http.request(
179            f"/api/v1/event_subscriptions/{subscription}",
180            method="PATCH",
181            body=input,
182            response_type=EventSubscription,
183        )
184
185    async def claim(
186        self, subscription: str, input: EventSubscriptionClaimInput
187    ) -> EventSubscriptionClaim:
188        """
189        Claim events from a subscription
190        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.
191
192        Args:
193            subscription: Subscription ID (`esub_...`).
194            input: Request body.
195            input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution.
196            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.
197            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.
198            input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds.
199            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.
200
201        Returns:
202            Successful response
203        """
204        return await self._http.request(
205            f"/api/v1/event_subscriptions/{subscription}/claim",
206            method="POST",
207            body=input,
208            response_type=EventSubscriptionClaim,
209        )
210
211    async def head(self, subscription: str) -> EventSubscriptionHead:
212        """
213        Peek at the head of a subscription queue
214        Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim.
215
216        Args:
217            subscription: Subscription ID (`esub_...`).
218
219        Returns:
220            Successful response
221        """
222        return await self._http.request(
223            f"/api/v1/event_subscriptions/{subscription}/head",
224            response_type=EventSubscriptionHead,
225        )
226
227    async def queue(
228        self,
229        subscription: str,
230        *,
231        limit: int | None = None,
232        before_cursor: str | None = None,
233        after_cursor: str | None = None,
234    ) -> EventSubscriptionQueue:
235        """
236        Read a subscription queue
237        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.
238
239        Args:
240            subscription: Subscription ID (`esub_...`).
241            limit: Maximum entries to return, from 1 through 100.
242            before_cursor: Opaque cursor for the preceding page.
243            after_cursor: Opaque cursor for the following page.
244
245        Returns:
246            Successful response
247        """
248        query: dict[str, object] = {}
249        if limit is not None:
250            query["limit"] = limit
251        if before_cursor is not None:
252            query["before_cursor"] = before_cursor
253        if after_cursor is not None:
254            query["after_cursor"] = after_cursor
255        return await self._http.request(
256            f"/api/v1/event_subscriptions/{subscription}/queue",
257            query=query,
258            response_type=EventSubscriptionQueue,
259        )
260
261
262class EventSubscriptionResource:
263    def __init__(self, http: SyncHttpClient):
264        self._http = http
265
266    def list(
267        self, *, page: int | None = None, per_page: int | None = None
268    ) -> EventSubscriptionPage:
269        """
270        List domain-event subscriptions
271        Lists the subscriptions visible to the caller, with current queue counters.
272
273        Args:
274            page: Page number, starting at 1.
275            per_page: Subscriptions per page, from 1 through 100.
276
277        Returns:
278            Subscriptions visible to this caller.
279        """
280        query: dict[str, object] = {}
281        if page is not None:
282            query["page"] = page
283        if per_page is not None:
284            query["per_page"] = per_page
285        return self._http.request(
286            "/api/v1/event_subscriptions",
287            query=query,
288            response_type=EventSubscriptionPage,
289        )
290
291    def create(self, input: EventSubscriptionCreateInput) -> EventSubscription:
292        """
293        Create a domain-event subscription
294        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.
295
296        Args:
297            input: Request body.
298            input.event_names: Exact event names to receive.
299            input.filter: Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events.
300            input.max_pending_events: Queue cap. Defaults to 100; maximum 1000.
301            input.name: Customer-defined subscription name.
302            input.previous_filter: Expected legacy filter for atomic watch-key adoption.
303            input.previous_filters: Additional exact historical filters accepted for atomic watch-key adoption.
304            input.previous_watch_key: Optionally adopt an existing key in the exact same owner and residence when the destination is absent and its filter exactly matches previous_filter, one of previous_filters, or filter. Preserves queue identity and deliveries; mismatches reject the request without changing either queue.
305            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
306            input.status: Initial status. Defaults to active.
307            input.visibility_timeout_seconds: Default claim lease in seconds. Defaults to 300.
308            input.watch_key: Optional durable identity within the caller owner and residence. Repeated creates replace routes and filter on that queue; omission creates a new queue regardless of name.
309
310        Returns:
311            The new volatile subscription.
312        """
313        return self._http.request(
314            "/api/v1/event_subscriptions",
315            method="POST",
316            body=input,
317            response_type=EventSubscription,
318        )
319
320    def delete(self, subscription: str) -> None:
321        """
322        Delete a domain-event subscription
323        Deletes the subscription and every delivery still in its queue.
324
325        Args:
326            subscription: Subscription ID (`esub_...`).
327
328        Returns:
329            No content
330        """
331        self._http.request(f"/api/v1/event_subscriptions/{subscription}", method="DELETE")
332
333    def get(self, subscription: str) -> EventSubscription:
334        """
335        Get a domain-event subscription
336        Returns one subscription and its current queue counters.
337
338        Args:
339            subscription: Subscription ID (`esub_...`).
340
341        Returns:
342            Successful response
343        """
344        return self._http.request(
345            f"/api/v1/event_subscriptions/{subscription}",
346            response_type=EventSubscription,
347        )
348
349    def update(self, subscription: str, input: EventSubscriptionUpdateInput) -> EventSubscription:
350        """
351        Update a domain-event subscription
352        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.
353
354        Args:
355            subscription: Subscription ID (`esub_...`).
356            input: Request body.
357            input.filter: Optional match over subject_key, actor_key, and allowlisted dims. Only valid when every event name is a custom (script-emitted) event type. Missing filter matches all events.
358            input.retention_seconds: Delivery retention in seconds. Defaults to 86400 (24 hours); between 7200 and 2592000. Applies to future deliveries only.
359
360        Returns:
361            Successful response
362        """
363        return self._http.request(
364            f"/api/v1/event_subscriptions/{subscription}",
365            method="PATCH",
366            body=input,
367            response_type=EventSubscription,
368        )
369
370    def claim(
371        self, subscription: str, input: EventSubscriptionClaimInput
372    ) -> EventSubscriptionClaim:
373        """
374        Claim events from a subscription
375        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.
376
377        Args:
378            subscription: Subscription ID (`esub_...`).
379            input: Request body.
380            input.consumer_id: Consumer identity between 1 and 128 bytes, recorded on the lease for attribution.
381            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.
382            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.
383            input.visibility_timeout_seconds: Lease duration override between 15 and 3600 seconds.
384            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.
385
386        Returns:
387            Successful response
388        """
389        return self._http.request(
390            f"/api/v1/event_subscriptions/{subscription}/claim",
391            method="POST",
392            body=input,
393            response_type=EventSubscriptionClaim,
394        )
395
396    def head(self, subscription: str) -> EventSubscriptionHead:
397        """
398        Peek at the head of a subscription queue
399        Returns the oldest unacknowledged delivery without reserving it. This diagnostic read cannot be used as a safe substitute for claim.
400
401        Args:
402            subscription: Subscription ID (`esub_...`).
403
404        Returns:
405            Successful response
406        """
407        return self._http.request(
408            f"/api/v1/event_subscriptions/{subscription}/head",
409            response_type=EventSubscriptionHead,
410        )
411
412    def queue(
413        self,
414        subscription: str,
415        *,
416        limit: int | None = None,
417        before_cursor: str | None = None,
418        after_cursor: str | None = None,
419    ) -> EventSubscriptionQueue:
420        """
421        Read a subscription queue
422        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.
423
424        Args:
425            subscription: Subscription ID (`esub_...`).
426            limit: Maximum entries to return, from 1 through 100.
427            before_cursor: Opaque cursor for the preceding page.
428            after_cursor: Opaque cursor for the following page.
429
430        Returns:
431            Successful response
432        """
433        query: dict[str, object] = {}
434        if limit is not None:
435            query["limit"] = limit
436        if before_cursor is not None:
437            query["before_cursor"] = before_cursor
438        if after_cursor is not None:
439            query["after_cursor"] = after_cursor
440        return self._http.request(
441            f"/api/v1/event_subscriptions/{subscription}/queue",
442            query=query,
443            response_type=EventSubscriptionQueue,
444        )