@homespunapps/core 1.6.64 → 1.6.65

package/dist/client.d.ts

@@ -652,6 +652,34 @@ export declare class HomespunClient {
     }>;
     /** DELETE /v1/apps/:id/connections/:name: idempotent. */
     deleteConnection(appId: string, name: string): Promise<void>;
+    /**
+     * GET /v1/apps/:id/webhooks/deliveries: the outbound delivery journal, newest
+     * first. This is a ROLLING window (the retention sweeper prunes terminal rows
+     * past WEBHOOKS_DELIVERY_RETENTION_DAYS), not the app's whole history.
+     *
+     * `payload` is the request body as it was rendered and sent, truncated
+     * server-side; `payloadTruncated` says whether it was cut. Together with
+     * `responseStatus`/`responseBody` that is what answers "why did the target
+     * reject this", which is the reason to reach for this call at all.
+     */
+    listWebhookDeliveries(appId: string, opts?: {
+        status?: string;
+        collection?: string;
+        limit?: number;
+    }): Promise<{
+        deliveries: Record<string, unknown>[];
+    }>;
+    /**
+     * POST /v1/apps/:id/webhooks/deliveries/:deliveryId/replay: re-send a stored
+     * delivery's own rule/url/payload as a fresh row, now, without waiting out
+     * its remaining backoff. Nothing caller-supplied enters the new row.
+     *
+     * NOT idempotent in effect: the target receives the same request again, so a
+     * target without its own dedupe ends up with a duplicate record.
+     */
+    replayWebhookDelivery(appId: string, deliveryId: string): Promise<{
+        delivery: Record<string, unknown>;
+    }>;
     /**
      * The browser URL that completes an oauth2 connection's consent. Build
      * only, never fetch this yourself: it 302s the caller to the third-party
@@ -667,8 +695,10 @@ export declare class HomespunClient {
      * conditions) and/or `sort` (`{field, dir}` list) to filter/order DB-side. The
      * relay applies read permission + author scoping FIRST, then the filter, so a
      * filtered read is always a subset of what the caller could already read. The
-     * query is serialized into the `q` param as URL-encoded JSON. Note: a custom
-     * `sort` cannot be combined with cursor pagination (`since`) in this version.
+     * query is serialized into the `q` param as URL-encoded JSON. Cursor
+     * pagination (`since`) works with a custom `sort` too (issue #1057): pass
+     * back the same `sort` a page's `next_cursor` came from, since a cursor is
+     * only valid for the exact sort it was issued under.
      */
     listAppRows(appId: string, collection: string, opts?: {
         since?: string;
@@ -887,6 +917,24 @@ export declare class HomespunClient {
     /** POST /v1/reviews/:id/unhold (operator): publish a held review. */
     unholdReview(reviewId: string): Promise<CommunityReview>;
 }
+/**
+ * PUT raw bytes to a presigned upload URL returned by `presignBlob()`.
+ * Deliberately a bare function, not a `HomespunClient` method: the URL is
+ * ALREADY pre-authorized (a SAS query string on Azure, scoped to this one
+ * key), so sending `Authorization: Bearer <apiKey>` alongside it would hand
+ * the agent's relay credential to a storage host that never asked for it and
+ * has no use for it. Routing this through `this.call` / `this.fetchImpl`
+ * would attach that header unconditionally, so this stays outside the
+ * authenticated client machinery on purpose.
+ *
+ * Azure Blob's single-shot PUT additionally requires the
+ * `x-ms-blob-type: BlockBlob` header; every presign backend today is Azure
+ * SAS, and a PUT without it 400s with `MissingRequiredHeader`, so it is
+ * always sent. There is no relay error envelope to parse on failure here:
+ * this response is storage's own, so a non-2xx throws a plain `Error`
+ * carrying the status and whatever body storage returned.
+ */
+export declare function putPresigned(uploadUrl: string, bytes: Uint8Array | Buffer, mime: string, fetchImpl?: typeof fetch): Promise<void>;
 /**
  * One multi-file-deploy asset carrying its bytes inline as base64. The deployed
  * page references it by a stable, app-relative, same-origin path (e.g.

package/dist/client.js

@@ -1104,6 +1104,44 @@ export class HomespunClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * GET /v1/apps/:id/webhooks/deliveries: the outbound delivery journal, newest
+     * first. This is a ROLLING window (the retention sweeper prunes terminal rows
+     * past WEBHOOKS_DELIVERY_RETENTION_DAYS), not the app's whole history.
+     *
+     * `payload` is the request body as it was rendered and sent, truncated
+     * server-side; `payloadTruncated` says whether it was cut. Together with
+     * `responseStatus`/`responseBody` that is what answers "why did the target
+     * reject this", which is the reason to reach for this call at all.
+     */
+    async listWebhookDeliveries(appId, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.status !== undefined)
+            q.set("status", opts.status);
+        if (opts.collection !== undefined)
+            q.set("collection", opts.collection);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/webhooks/deliveries${qs ? `?${qs}` : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/apps/:id/webhooks/deliveries/:deliveryId/replay: re-send a stored
+     * delivery's own rule/url/payload as a fresh row, now, without waiting out
+     * its remaining backoff. Nothing caller-supplied enters the new row.
+     *
+     * NOT idempotent in effect: the target receives the same request again, so a
+     * target without its own dedupe ends up with a duplicate record.
+     */
+    async replayWebhookDelivery(appId, deliveryId) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/webhooks/deliveries/${encodeURIComponent(deliveryId)}/replay`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * The browser URL that completes an oauth2 connection's consent. Build
      * only, never fetch this yourself: it 302s the caller to the third-party
@@ -1126,8 +1164,10 @@ export class HomespunClient {
      * conditions) and/or `sort` (`{field, dir}` list) to filter/order DB-side. The
      * relay applies read permission + author scoping FIRST, then the filter, so a
      * filtered read is always a subset of what the caller could already read. The
-     * query is serialized into the `q` param as URL-encoded JSON. Note: a custom
-     * `sort` cannot be combined with cursor pagination (`since`) in this version.
+     * query is serialized into the `q` param as URL-encoded JSON. Cursor
+     * pagination (`since`) works with a custom `sort` too (issue #1057): pass
+     * back the same `sort` a page's `next_cursor` came from, since a cursor is
+     * only valid for the exact sort it was issued under.
      */
     async listAppRows(appId, collection, opts = {}) {
         const q = new URLSearchParams();
@@ -1554,6 +1594,45 @@ export class HomespunClient {
         return this.asObject(r);
     }
 }
+/**
+ * PUT raw bytes to a presigned upload URL returned by `presignBlob()`.
+ * Deliberately a bare function, not a `HomespunClient` method: the URL is
+ * ALREADY pre-authorized (a SAS query string on Azure, scoped to this one
+ * key), so sending `Authorization: Bearer <apiKey>` alongside it would hand
+ * the agent's relay credential to a storage host that never asked for it and
+ * has no use for it. Routing this through `this.call` / `this.fetchImpl`
+ * would attach that header unconditionally, so this stays outside the
+ * authenticated client machinery on purpose.
+ *
+ * Azure Blob's single-shot PUT additionally requires the
+ * `x-ms-blob-type: BlockBlob` header; every presign backend today is Azure
+ * SAS, and a PUT without it 400s with `MissingRequiredHeader`, so it is
+ * always sent. There is no relay error envelope to parse on failure here:
+ * this response is storage's own, so a non-2xx throws a plain `Error`
+ * carrying the status and whatever body storage returned.
+ */
+export async function putPresigned(uploadUrl, bytes, mime, fetchImpl = fetch) {
+    const body = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let res;
+    try {
+        res = await fetchImpl(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "content-type": mime,
+                "x-ms-blob-type": "BlockBlob",
+            },
+            body,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`presigned upload failed: ${msg}`, { cause: e });
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`presigned upload failed: HTTP ${res.status}${text ? ` (${text.slice(0, 500)})` : ""}`);
+    }
+}
 /**
  * Path for a community-template ref action. A namespaced `<handle>/<slug>` ref
  * becomes a TWO-segment path (`/templates/<handle>/<slug>/<suffix>`) so it

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { HomespunClient, HomespunApiError } from "./client.js";
+export { HomespunClient, HomespunApiError, putPresigned } from "./client.js";
 export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, AppAsset, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, DeployCheckRequest, DeployCheckResult, KeyMintResult, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, ListScalar, ListWhereCondition, ListSortSpec, BatchRowInput, BatchRowResult, BatchResult, BatchWriteOptions, AppFeedEntry, AppFeedPage, CommunitySetupStep, RetentionAxes, CollectionRetentionView, ServiceCredentialGrant, MintAppCredentialResult, AppCredentialSummary, RotateAppCredentialResult, ConnectionSummary, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 // @homespunapps/core — typed client for the Homespun relay HTTP + WebSocket API.
 // Pure and framework-free: no argv, no MCP, no server deps.
-export { HomespunClient, HomespunApiError } from "./client.js";
+export { HomespunClient, HomespunApiError, putPresigned } from "./client.js";
 export { openStream } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
 export { openWorkerStream, workerWsUrlFromBase } from "./app-stream.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/core",
-  "version": "1.6.64",
+  "version": "1.6.65",
   "description": "Homespun relay client: typed HTTP + WebSocket operations against a Homespun relay. Framework-free.",
   "license": "MIT",
   "type": "module",