palbase 0.0.0-stage → 0.1.0

package/types/internal/src/modules/cache.d.ts

@@ -0,0 +1,158 @@
+import { type Reply, type Transport } from '../transport.js';
+/**
+ * An entry's count.
+ */
+export type CacheCounter = {
+    /**
+     * The count after this increment.
+     */
+    value: number;
+};
+/**
+ * A read's answer.
+ */
+export type CacheEntry = {
+    /**
+     * The seconds the entry has left, rounded up; absent when there is none.
+     */
+    expires_in?: number;
+    /**
+     * Whether the key holds an entry.
+     */
+    found: boolean;
+    /**
+     * The JSON the entry was written with; absent when there is none. A written `null` is `found: true` with `value: null`.
+     */
+    value?: unknown;
+};
+/**
+ * A delete's answer.
+ */
+export type CacheEntryDeleted = {
+    /**
+     * Whether there was an entry.
+     */
+    deleted: boolean;
+};
+/**
+ * An entry's new value.
+ */
+export type CacheEntryWrite = {
+    /**
+     * The seconds the entry lasts, 1 to 2592000 (thirty days); thirty days without it.
+     */
+    ttl?: number;
+    /**
+     * Any JSON, 512 KiB at most as it is sent.
+     */
+    value: unknown;
+};
+/**
+ * A write's answer.
+ */
+export type CacheEntryWritten = {
+    /**
+     * How many of the project's own entries were dropped to keep it under its quota.
+     */
+    evicted: number;
+    /**
+     * The seconds the entry lasts.
+     */
+    expires_in: number;
+};
+/**
+ * What a project's entries weigh.
+ */
+export type CacheUsage = {
+    /**
+     * What the live entries weigh together: each its value and its key three times, a quarter more, and 320 bytes.
+     */
+    bytes: number;
+    /**
+     * How many live entries there are.
+     */
+    entries: number;
+    /**
+     * The quota they stay under.
+     */
+    limit_bytes: number;
+};
+export type ErrorResponse = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID for log/audit lookup
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying; present on a refusal that ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code (mirrors the response status)
+     */
+    status: number;
+};
+/** Palbase Cache */
+export declare function client(t: Transport): {
+    /**
+     * Read an entry
+     *
+     * Reads the entry of `key`. A key that holds nothing, or whose entry ran out, is not an error: the answer says `found: false`.
+     */
+    getCacheEntry(input: {
+        query: {
+            key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CacheEntry>>;
+    /**
+     * Write an entry
+     *
+     * Writes the value under `key` for `ttl` seconds (thirty days without one, and at most), replacing what was there. A value is any JSON, 512 KiB at most. Writing the same value again changes nothing but the time left, so the call is safe to send again. When the project's entries would pass its quota the ones nearest their end are dropped first (`evicted`).
+     */
+    putCacheEntry(input: {
+        query: {
+            key: string;
+        };
+        body: CacheEntryWrite; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CacheEntryWritten>>;
+    /**
+     * Delete an entry
+     *
+     * Deletes the entry of `key`. Deleting what is not there is not an error (`deleted: false`), so the call is safe to send again.
+     */
+    deleteCacheEntry(input: {
+        query: {
+            key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CacheEntryDeleted>>;
+    /**
+     * Count up an entry
+     *
+     * Adds one to the entry's count and answers the new count, atomically: two callers never get the same number. An entry that is not there, or holds something that is not a whole number, counts from zero. A count keeps the time it had left; a new one lasts thirty days. A count stops short of sixteen digits. Sent again, it counts again — and when the cache could not be reached (503) the count may already have been taken.
+     */
+    incrementCacheEntry(input: {
+        query: {
+            key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CacheCounter>>;
+    /**
+     * Read the cache's usage
+     *
+     * What the project's live entries weigh together, the quota they stay under, and how many there are.
+     */
+    getCacheUsage(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CacheUsage>>;
+};
+export type Client = ReturnType<typeof client>;

package/types/internal/src/modules/events.d.ts

@@ -0,0 +1,19 @@
+import type { WebhookEvent } from '../event.js';
+import type { Events as AiEvents } from './ai.js';
+import type { Events as PurchasesEvents } from './purchases.js';
+import type { Events as StorageEvents } from './storage.js';
+import type { Events as StoresEvents } from './stores.js';
+/** Every event the modules' contracts say they send the project's webhooks (x-palbase-events), by type: its payload, the event's data. */
+export interface PlatformEvents extends AiEvents, PurchasesEvents, StorageEvents, StoresEvents {
+}
+/** A platform event's type: one a module's contract declares. */
+export type EventType = keyof PlatformEvents;
+/** Every platform event's type, as the contracts declare them. */
+export declare const EVENT_TYPES: readonly ["ai.response.completed", "ai.response.failed", "file.deleted", "file.moved", "file.uploaded", "purchases.catalog.applied", "purchases.catalog.changed", "purchases.credits.depleted", "purchases.credits.low", "purchases.customer.changed", "purchases.customer.erased", "purchases.customer.merged", "purchases.entitlement.changed", "purchases.ownership.transferred", "purchases.purchase.completed", "purchases.quota.exhausted", "purchases.quota.threshold", "purchases.refund.changed", "purchases.store.changed", "purchases.subscription.changed", "stores.action.changed", "stores.app.changed", "stores.apple.changed", "stores.delivery.changed", "stores.delivery.requested", "stores.group.changed", "stores.package.changed"];
+/**
+ * A platform event as delivered: one member per type the contracts declare,
+ * its data that type's payload, so a switch on its type narrows it. An
+ * event of a type none of them declares (one a newer platform sends) is no
+ * member: at run time it reaches the switch's default, which takes it.
+ */
+export type PalbaseEvent = WebhookEvent<PlatformEvents["ai.response.completed"], "ai.response.completed"> | WebhookEvent<PlatformEvents["ai.response.failed"], "ai.response.failed"> | WebhookEvent<PlatformEvents["file.deleted"], "file.deleted"> | WebhookEvent<PlatformEvents["file.moved"], "file.moved"> | WebhookEvent<PlatformEvents["file.uploaded"], "file.uploaded"> | WebhookEvent<PlatformEvents["purchases.catalog.applied"], "purchases.catalog.applied"> | WebhookEvent<PlatformEvents["purchases.catalog.changed"], "purchases.catalog.changed"> | WebhookEvent<PlatformEvents["purchases.credits.depleted"], "purchases.credits.depleted"> | WebhookEvent<PlatformEvents["purchases.credits.low"], "purchases.credits.low"> | WebhookEvent<PlatformEvents["purchases.customer.changed"], "purchases.customer.changed"> | WebhookEvent<PlatformEvents["purchases.customer.erased"], "purchases.customer.erased"> | WebhookEvent<PlatformEvents["purchases.customer.merged"], "purchases.customer.merged"> | WebhookEvent<PlatformEvents["purchases.entitlement.changed"], "purchases.entitlement.changed"> | WebhookEvent<PlatformEvents["purchases.ownership.transferred"], "purchases.ownership.transferred"> | WebhookEvent<PlatformEvents["purchases.purchase.completed"], "purchases.purchase.completed"> | WebhookEvent<PlatformEvents["purchases.quota.exhausted"], "purchases.quota.exhausted"> | WebhookEvent<PlatformEvents["purchases.quota.threshold"], "purchases.quota.threshold"> | WebhookEvent<PlatformEvents["purchases.refund.changed"], "purchases.refund.changed"> | WebhookEvent<PlatformEvents["purchases.store.changed"], "purchases.store.changed"> | WebhookEvent<PlatformEvents["purchases.subscription.changed"], "purchases.subscription.changed"> | WebhookEvent<PlatformEvents["stores.action.changed"], "stores.action.changed"> | WebhookEvent<PlatformEvents["stores.app.changed"], "stores.app.changed"> | WebhookEvent<PlatformEvents["stores.apple.changed"], "stores.apple.changed"> | WebhookEvent<PlatformEvents["stores.delivery.changed"], "stores.delivery.changed"> | WebhookEvent<PlatformEvents["stores.delivery.requested"], "stores.delivery.requested"> | WebhookEvent<PlatformEvents["stores.group.changed"], "stores.group.changed"> | WebhookEvent<PlatformEvents["stores.package.changed"], "stores.package.changed">;