@protobase/schema 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { InferRecord, RecordKey } from "./resource-types.js";
 import { resource } from "./resource.js";
 import { checkEventFilter } from "./events/event-models.js";
 import { view } from "./view.js";
+import { webhookResources } from "./webhooks/webhook-resources.js";
 import { enumLabel } from "./enum-label.js";
 import { SearchTerm, matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
 import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
@@ -32,4 +33,4 @@ import "./access/index.js";
 import { AssistantAction, AssistantActionRequest, AssistantCardPart, AssistantDiff, AssistantEvent, AssistantMessage, AssistantMessageRequest, AssistantPart, AssistantState, AssistantStep, AssistantStepState, AssistantTablePart, AssistantTextPart, AssistantTone, AssistantWidgetPart } from "./assistant/protocol.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FileField, type FileFieldModel, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, applyAssistantEvent, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };
+export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FileField, type FileFieldModel, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, applyAssistantEvent, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, webhookResources, where };

package/dist/index.js

@@ -9,12 +9,13 @@ import { createWhere, where } from "./filter/where.js";
 import { accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./access/resolve.js";
 import { checkEventFilter } from "./events/event-models.js";
 import { resource } from "./resource.js";
+import { layout } from "./layout.js";
 import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
 import { view } from "./view.js";
+import { webhookResources } from "./webhooks/webhook-resources.js";
 import { enumLabel } from "./enum-label.js";
 import { matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
 import { userMenu } from "./user-menu.js";
-import { layout } from "./layout.js";
 import { decodeKey, encodeKey, keyTypes } from "./keys.js";
 import { rule } from "./access/rule.js";
 import { defineRoles } from "./access/roles.js";
@@ -22,4 +23,4 @@ import { pickView } from "./access/pick-view.js";
 import { restrictModel } from "./access/restrict.js";
 import { applyAssistantEvent, emptyAssistantState } from "./assistant/apply-event.js";
 import { readEventStream } from "./assistant/event-stream.js";
-export { accessWarnings, applyAssistantEvent, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };
+export { accessWarnings, applyAssistantEvent, checkEventFilter, checkFilter, checkOrderBy, checkRecord, checkedAccept, checkedProvider, createWhere, decodeKey, defaultRecentLimit, defineRoles, emptyAssistantState, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, parseSize, pickView, printFilter, printOrderBy, readEventStream, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, webhookResources, where };

package/dist/webhooks/webhook-resources.d.ts

@@ -0,0 +1,113 @@
+import { Field } from "../field.js";
+import { Ref } from "../refs.js";
+import { ResourceBuilder } from "../resource.js";
+import { ViewBuilder } from "../view.js";
+import "../index.js";
+//#region src/webhooks/webhook-resources.d.ts
+/**
+ * The resources and views `webhooks()` adds to an app, over the tables and the view of `schema`: Webhook subscriptions,
+ * Webhook deliveries and, with `deliveryLog`, Webhook delivery log. Config only; the server delivers.
+ */
+export declare const webhookResources: (schema: string, { deliveryLog }?: {
+  deliveryLog?: boolean;
+}) => {
+  webhookDeliveryLog?: ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly subscriptionId: Field<string | number>;
+    readonly tenantId: Field<string | null>;
+    readonly eventId: Field<string>;
+    readonly eventType: Field<string>;
+    readonly status: Field<"failed" | "delivered">;
+    readonly attempt: Field<number>;
+    readonly statusCode: Field<number | null>;
+    readonly response: Field<string | null>;
+    readonly durationMs: Field<number>;
+    readonly at: Field<string>;
+  }, Ref<"id", string>> | undefined;
+  webhookDeliveryLogView?: ViewBuilder<ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly subscriptionId: Field<string | number>;
+    readonly tenantId: Field<string | null>;
+    readonly eventId: Field<string>;
+    readonly eventType: Field<string>;
+    readonly status: Field<"failed" | "delivered">;
+    readonly attempt: Field<number>;
+    readonly statusCode: Field<number | null>;
+    readonly response: Field<string | null>;
+    readonly durationMs: Field<number>;
+    readonly at: Field<string>;
+  }, Ref<"id", string>>> | undefined;
+  webhookSubscriptions: ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly name: Field<string>;
+    readonly events: Field<string>;
+    readonly url: Field<string>;
+    readonly filter: Field<string | null>;
+    readonly headers: Field<import("zod").JSONType>;
+    readonly payload: Field<"full" | "thin">;
+    readonly enabled: Field<boolean>;
+    readonly secret: Field<string>;
+    readonly previousSecret: null;
+    readonly previousSecretUntil: null;
+    readonly tenantId: Field<string | null>;
+    readonly ownerId: Field<string | null>;
+    readonly disabledReason: Field<string | null>;
+    readonly lastSuccessAt: Field<string | null>;
+    readonly failingSince: Field<string | null>;
+    readonly createdAt: Field<string>;
+    readonly updatedAt: Field<string>;
+    readonly rotateSecret: Field<boolean>;
+    readonly sendTest: Field<boolean>;
+    readonly resendFailed: Field<boolean>;
+  }, Ref<"id", string>>;
+  webhookSubscriptionsView: ViewBuilder<ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly name: Field<string>;
+    readonly events: Field<string>;
+    readonly url: Field<string>;
+    readonly filter: Field<string | null>;
+    readonly headers: Field<import("zod").JSONType>;
+    readonly payload: Field<"full" | "thin">;
+    readonly enabled: Field<boolean>;
+    readonly secret: Field<string>;
+    readonly previousSecret: null;
+    readonly previousSecretUntil: null;
+    readonly tenantId: Field<string | null>;
+    readonly ownerId: Field<string | null>;
+    readonly disabledReason: Field<string | null>;
+    readonly lastSuccessAt: Field<string | null>;
+    readonly failingSince: Field<string | null>;
+    readonly createdAt: Field<string>;
+    readonly updatedAt: Field<string>;
+    readonly rotateSecret: Field<boolean>;
+    readonly sendTest: Field<boolean>;
+    readonly resendFailed: Field<boolean>;
+  }, Ref<"id", string>>>;
+  webhookDeliveries: ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly subscriptionId: Field<string | number>;
+    readonly tenantId: Field<string | null>;
+    readonly eventType: Field<string>;
+    readonly eventId: Field<string>;
+    readonly status: Field<"waiting" | "failed">;
+    readonly attempt: Field<number>;
+    readonly nextAttempt: Field<string | null>;
+    readonly lastError: Field<string | null>;
+    readonly createdAt: Field<string>;
+    readonly resend: Field<boolean>;
+  }, Ref<"id", string>>;
+  webhookDeliveriesView: ViewBuilder<ResourceBuilder<{
+    readonly id: Field<string>;
+    readonly subscriptionId: Field<string | number>;
+    readonly tenantId: Field<string | null>;
+    readonly eventType: Field<string>;
+    readonly eventId: Field<string>;
+    readonly status: Field<"waiting" | "failed">;
+    readonly attempt: Field<number>;
+    readonly nextAttempt: Field<string | null>;
+    readonly lastError: Field<string | null>;
+    readonly createdAt: Field<string>;
+    readonly resend: Field<boolean>;
+  }, Ref<"id", string>>>;
+};
+//#endregion

package/dist/webhooks/webhook-resources.js

@@ -0,0 +1,211 @@
+import { f } from "../fields.js";
+import { resource } from "../resource.js";
+import { layout } from "../layout.js";
+import { view } from "../view.js";
+//#region src/webhooks/webhook-resources.ts
+/** Webhook subscriptions: a row per subscription someone made in the admin app, scoped to their tenant. */
+const subscriptionsResource = (schema) => resource("webhookSubscriptions").table(`${schema}.subscriptions`).fields({
+	id: f.uuid().readOnly().dbDefault(),
+	name: f.text().min(1).max(100).filterable().sortable(),
+	events: f.text().min(1).max(2e3),
+	url: f.text().max(2e3).regex(/^https?:\/\/[^\s/]+/, "Use an http:// or https:// URL"),
+	filter: f.text().optional().max(2e3),
+	headers: f.json().optional(),
+	payload: f.enum(["full", "thin"]).default("full"),
+	enabled: f.boolean().default(true).filterable(),
+	secret: f.text().sensitive().readOnly().dbDefault(),
+	previousSecret: null,
+	previousSecretUntil: null,
+	tenantId: f.text().optional().readOnly(),
+	ownerId: f.text().optional().readOnly().dbDefault(),
+	disabledReason: f.text().optional().readOnly(),
+	lastSuccessAt: f.timestamp().optional().readOnly().sortable(),
+	failingSince: f.timestamp().optional().readOnly(),
+	createdAt: f.timestamp().readOnly().dbDefault().sortable(),
+	updatedAt: f.timestamp().readOnly().dbDefault(),
+	rotateSecret: f.boolean().default(false),
+	sendTest: f.boolean().default(false),
+	resendFailed: f.boolean().default(false)
+}).primaryKey((r) => r.id).tenant((r) => r.tenantId).owner((r) => r.ownerId).search((r) => [r.name, r.url]);
+const subscriptionsView = view("webhookSubscriptions").names({
+	singular: "Webhook subscription",
+	plural: "Webhook subscriptions"
+}).icon("webhook").title((r) => r.name).help("Sends the app's events to a URL as they happen, signed with Standard Webhooks. It delivers as its owner: only the records and fields they may read.").fields((r) => ({
+	events: r.events.help("Event names separated by spaces, such as orders.created, or orders.* for every event of a resource"),
+	url: r.url.label("URL"),
+	filter: r.filter.help("Only records that match, in the language of filters: status = \"paid\""),
+	headers: r.headers.help("Extra request headers, as a JSON object"),
+	payload: r.payload.help("Thin leaves the records out: the receiver reads them through the API").valueLabels({
+		full: "Full",
+		thin: "Thin"
+	}),
+	secret: r.secret.help("Receivers check the webhook-signature header with it"),
+	disabledReason: r.disabledReason.label("Disabled because"),
+	lastSuccessAt: r.lastSuccessAt.label("Last success"),
+	failingSince: r.failingSince.label("Failing since")
+})).list((r) => ({
+	columns: [
+		r.name,
+		r.events,
+		r.url,
+		r.enabled,
+		r.lastSuccessAt
+	],
+	sort: [[r.createdAt, "desc"]]
+})).layout((r) => [
+	layout.section("Subscription", [
+		r.name,
+		r.events,
+		r.url,
+		r.filter,
+		r.payload,
+		r.headers,
+		r.enabled
+	]),
+	layout.section("Signing", [r.secret]),
+	layout.sidebar([
+		r.lastSuccessAt,
+		r.failingSince,
+		r.disabledReason,
+		r.createdAt
+	]),
+	layout.related("Waiting and failed deliveries", {
+		resource: "webhookDeliveries",
+		field: "subscriptionId",
+		columns: [
+			"eventType",
+			"status",
+			"attempt",
+			"nextAttempt",
+			"lastError"
+		]
+	})
+]).actions((a) => [
+	a.update("sendTest", {
+		label: "Send test event",
+		icon: "send",
+		set: { sendTest: true }
+	}),
+	a.update("resendFailed", {
+		label: "Resend failed",
+		icon: "rotate-ccw",
+		set: { resendFailed: true },
+		confirm: "Try every failed delivery of this subscription once more?"
+	}),
+	a.update("rotateSecret", {
+		label: "Rotate secret",
+		icon: "key-round",
+		set: { rotateSecret: true },
+		confirm: "Make a new secret? The old one keeps signing too for 24 hours."
+	}),
+	a.update("disable", {
+		label: "Disable",
+		icon: "pause",
+		set: { enabled: false }
+	})
+]);
+/** The deliveries of webhook subscriptions that wait for a retry or failed for good: delivery jobs, not a table. */
+const deliveriesResource = (schema) => resource("webhookDeliveries").table(`${schema}.deliveries`).fields({
+	id: f.uuid().readOnly(),
+	subscriptionId: f.relation("webhookSubscriptions").readOnly().filterable(),
+	tenantId: f.text().optional().readOnly(),
+	eventType: f.text().readOnly().filterable().sortable(),
+	eventId: f.text().readOnly().filterable(),
+	status: f.enum(["waiting", "failed"]).readOnly().filterable(),
+	attempt: f.integer().readOnly(),
+	nextAttempt: f.timestamp().optional().readOnly().sortable(),
+	lastError: f.text().optional().readOnly(),
+	createdAt: f.timestamp().readOnly().sortable(),
+	resend: f.boolean()
+}).primaryKey((r) => r.id).tenant((r) => r.tenantId).access({
+	create: () => false,
+	delete: () => false
+});
+const deliveriesView = view("webhookDeliveries").names({
+	singular: "Webhook delivery",
+	plural: "Webhook deliveries"
+}).icon("send").title((r) => r.eventType).help("Deliveries that wait for their next try or failed for good. A delivery leaves the list once it succeeds.").fields((r) => ({
+	eventType: r.eventType.label("Event"),
+	eventId: r.eventId.label("Event id").format("code"),
+	nextAttempt: r.nextAttempt.label("Next try"),
+	lastError: r.lastError.label("Last error"),
+	attempt: r.attempt.label("Tries")
+})).list((r) => ({
+	columns: [
+		r.eventType,
+		r.subscriptionId,
+		r.status,
+		r.attempt,
+		r.nextAttempt,
+		r.lastError
+	],
+	sort: [[r.createdAt, "desc"]]
+})).layout((r) => [layout.section("Delivery", [
+	r.subscriptionId,
+	r.eventType,
+	r.eventId,
+	r.lastError
+]), layout.sidebar([
+	r.status,
+	r.attempt,
+	r.nextAttempt,
+	r.createdAt
+])]).actions((a) => [a.update("resend", {
+	label: "Resend",
+	icon: "rotate-ccw",
+	set: { resend: true },
+	confirm: "Try this delivery once more, from now?"
+})]);
+/** Every try of every webhook subscription's deliveries, for 30 days (`deliveryLog: true`). */
+const deliveryLogResource = (schema) => resource("webhookDeliveryLog").table(`${schema}.delivery_log`).fields({
+	id: f.bigint().readOnly(),
+	subscriptionId: f.relation("webhookSubscriptions").readOnly().filterable(),
+	tenantId: f.text().optional().readOnly(),
+	eventId: f.text().readOnly().filterable(),
+	eventType: f.text().readOnly().filterable().sortable(),
+	status: f.enum(["delivered", "failed"]).readOnly().filterable(),
+	attempt: f.integer().readOnly(),
+	statusCode: f.integer().optional().readOnly().filterable(),
+	response: f.text().optional().readOnly(),
+	durationMs: f.integer().readOnly(),
+	at: f.timestamp().readOnly().filterable().sortable()
+}).primaryKey((r) => r.id).tenant((r) => r.tenantId).access({
+	create: () => false,
+	update: () => false,
+	delete: () => false
+});
+const deliveryLogView = view("webhookDeliveryLog").names({
+	singular: "Webhook delivery log entry",
+	plural: "Webhook delivery log"
+}).icon("scroll-text").title((r) => r.eventType).fields((r) => ({
+	eventType: r.eventType.label("Event"),
+	statusCode: r.statusCode.label("Status code"),
+	durationMs: r.durationMs.label("Duration (ms)"),
+	at: r.at.label("When")
+})).list((r) => ({
+	columns: [
+		r.at,
+		r.eventType,
+		r.subscriptionId,
+		r.status,
+		r.statusCode,
+		r.durationMs
+	],
+	sort: [[r.at, "desc"]]
+}));
+/**
+* The resources and views `webhooks()` adds to an app, over the tables and the view of `schema`: Webhook subscriptions,
+* Webhook deliveries and, with `deliveryLog`, Webhook delivery log. Config only; the server delivers.
+*/
+const webhookResources = (schema, { deliveryLog = false } = {}) => ({
+	webhookSubscriptions: subscriptionsResource(schema),
+	webhookSubscriptionsView: subscriptionsView,
+	webhookDeliveries: deliveriesResource(schema),
+	webhookDeliveriesView: deliveriesView,
+	...deliveryLog && {
+		webhookDeliveryLog: deliveryLogResource(schema),
+		webhookDeliveryLogView: deliveryLogView
+	}
+});
+//#endregion
+export { webhookResources };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/schema",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Resource, field, view and access definitions for Protobase configs.",
   "license": "Apache-2.0",
   "repository": {