@sealant/api-contracts-next 0.40.0-next.769 → 0.40.0-next.770

package/dist/core-api/resource-domains.d.ts

@@ -15,6 +15,17 @@
  * before a handler runs. A deployment served without authentication (the development exception)
  * serves them as it serves every other route. A request body is decoded strictly: a field the contract does not declare (an
  * owner, a credential) is refused with `400` instead of being dropped.
+ *
+ * Members are the people the application lets reach the domain. A grant or a revoke carries
+ * `version`, the application's own number for its decision about this person, rising with each
+ * decision it makes (its record's revision, say). Core writes the decision only over a lower
+ * version. The same version with the same state is a repeat, answered with the member unchanged.
+ * The same version with the other state, or a lower one, is stale: `409`, carrying the decision
+ * that stands. So a delayed grant never undoes a newer revoke, whatever order decisions arrive in
+ * and however often each is retried, and the application never reads before it writes. A revoke
+ * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
+ * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
+ * `nextCursor` as `cursor`.
  */
 import { Schema } from "effect";
 import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
@@ -36,6 +47,40 @@ export declare const ensureResourceDomainResponseSchema: Schema.Struct<{
     readonly created: Schema.Boolean;
 }>;
 export type EnsureResourceDomainResponse = typeof ensureResourceDomainResponseSchema.Type;
+export declare const resourceDomainMemberSchema: Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>;
+export type ResourceDomainMemberWire = typeof resourceDomainMemberSchema.Type;
+export declare const resourceDomainMemberDecisionSchema: Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>;
+export type ResourceDomainMemberDecisionRequest = typeof resourceDomainMemberDecisionSchema.Type;
+/** At most this many members a page, and this many when the request names no `limit`. */
+export declare const RESOURCE_DOMAIN_MEMBERS_PAGE: {
+    readonly default: 100;
+    readonly max: 500;
+};
+export declare const listResourceDomainMembersQuerySchema: Schema.Struct<{
+    readonly limit: Schema.optional<Schema.FiniteFromString>;
+    /** A previous page's `nextCursor`: the page starts after it. */
+    readonly cursor: Schema.optional<Schema.String>;
+}>;
+export type ListResourceDomainMembersQuery = typeof listResourceDomainMembersQuerySchema.Type;
+export declare const listResourceDomainMembersResponseSchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly userId: Schema.String;
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+        readonly updatedAt: Schema.String;
+    }>>;
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    readonly nextCursor: Schema.optional<Schema.String>;
+}>;
+export type ListResourceDomainMembersResponse = typeof listResourceDomainMembersResponseSchema.Type;
 declare const ResourceDomainForbiddenError_base: Schema.Class<ResourceDomainForbiddenError, Schema.TaggedStruct<"ResourceDomainForbiddenError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -46,6 +91,31 @@ declare const ResourceDomainNotFoundError_base: Schema.Class<ResourceDomainNotFo
 }>, import("effect/Cause").YieldableError>;
 export declare class ResourceDomainNotFoundError extends ResourceDomainNotFoundError_base {
 }
+declare const ResourceDomainPersonNotFoundError_base: Schema.Class<ResourceDomainPersonNotFoundError, Schema.TaggedStruct<"ResourceDomainPersonNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The person a member route names does not exist (the domain does). */
+export declare class ResourceDomainPersonNotFoundError extends ResourceDomainPersonNotFoundError_base {
+}
+declare const ResourceDomainMemberNotFoundError_base: Schema.Class<ResourceDomainMemberNotFoundError, Schema.TaggedStruct<"ResourceDomainMemberNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The person exists, and the application has made no decision about them in the domain. */
+export declare class ResourceDomainMemberNotFoundError extends ResourceDomainMemberNotFoundError_base {
+}
+declare const ResourceDomainMemberVersionConflictError_base: Schema.Class<ResourceDomainMemberVersionConflictError, Schema.TaggedStruct<"ResourceDomainMemberVersionConflictError", {
+    readonly message: Schema.String;
+    readonly current: Schema.Struct<{
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A decision at least as new stands, so this one changed nothing. `current` is the decision that
+ * stands; the message quotes nothing the request sent.
+ */
+export declare class ResourceDomainMemberVersionConflictError extends ResourceDomainMemberVersionConflictError_base {
+}
 declare const ResourceDomainInternalServerError_base: Schema.Class<ResourceDomainInternalServerError, Schema.TaggedStruct<"ResourceDomainInternalServerError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -65,5 +135,50 @@ export declare const ResourceDomainsGroup: HttpApiGroup.HttpApiGroup<"resourceDo
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
     readonly createdAt: Schema.String;
-}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never>, false>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomainMember", "GET", "/:resourceDomainId/members/:userId", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"grantResourceDomainMember", "POST", "/:resourceDomainId/members/:userId/grant", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listResourceDomainMembers", "GET", "/:resourceDomainId/members", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, Schema.toCodecStringTree<Schema.Struct<{
+    readonly limit: Schema.optional<Schema.FiniteFromString>;
+    /** A previous page's `nextCursor`: the page starts after it. */
+    readonly cursor: Schema.optional<Schema.String>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly userId: Schema.String;
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+        readonly updatedAt: Schema.String;
+    }>>;
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    readonly nextCursor: Schema.optional<Schema.String>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"revokeResourceDomainMember", "POST", "/:resourceDomainId/members/:userId/revoke", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never>, false>;
 export {};

package/dist/core-api/resource-domains.js

@@ -15,10 +15,21 @@
  * before a handler runs. A deployment served without authentication (the development exception)
  * serves them as it serves every other route. A request body is decoded strictly: a field the contract does not declare (an
  * owner, a credential) is refused with `400` instead of being dropped.
+ *
+ * Members are the people the application lets reach the domain. A grant or a revoke carries
+ * `version`, the application's own number for its decision about this person, rising with each
+ * decision it makes (its record's revision, say). Core writes the decision only over a lower
+ * version. The same version with the same state is a repeat, answered with the member unchanged.
+ * The same version with the other state, or a lower one, is stale: `409`, carrying the decision
+ * that stands. So a delayed grant never undoes a newer revoke, whatever order decisions arrive in
+ * and however often each is retried, and the application never reads before it writes. A revoke
+ * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
+ * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
+ * `nextCursor` as `cursor`.
  */
 import { Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api";
-import { RESOURCE_DOMAIN_ID_PREFIX } from "./person-id.js";
+import { PersonId, RESOURCE_DOMAIN_ID_PREFIX } from "./person-id.js";
 const RESOURCE_DOMAIN_ID_PATTERN = new RegExp(`^${RESOURCE_DOMAIN_ID_PREFIX}[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`);
 const RESOURCE_DOMAIN_KEY_PATTERN = /^[a-z][a-z0-9-]{0,31}:[A-Za-z0-9._:/@+=-]{1,223}$/;
 const ResourceDomainId = Schema.String.check(Schema.makeFilter((id) => RESOURCE_DOMAIN_ID_PATTERN.test(id) ? undefined : "must be a resource domain id (rdm:<uuid>)"));
@@ -36,12 +47,59 @@ export const ensureResourceDomainResponseSchema = Schema.Struct({
     /** True when this call created the domain. */
     created: Schema.Boolean,
 });
+const MemberVersion = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }));
+const MemberState = Schema.Literals(["member", "revoked"]);
+export const resourceDomainMemberSchema = Schema.Struct({
+    userId: PersonId,
+    state: MemberState,
+    version: MemberVersion,
+    updatedAt: Schema.String,
+});
+export const resourceDomainMemberDecisionSchema = Schema.Struct({
+    /** The application's own version of this decision, rising with each decision it makes. */
+    version: MemberVersion,
+});
+/** At most this many members a page, and this many when the request names no `limit`. */
+export const RESOURCE_DOMAIN_MEMBERS_PAGE = { default: 100, max: 500 };
+export const listResourceDomainMembersQuerySchema = Schema.Struct({
+    limit: Schema.optional(Schema.FiniteFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: RESOURCE_DOMAIN_MEMBERS_PAGE.max }))),
+    /** A previous page's `nextCursor`: the page starts after it. */
+    cursor: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
+});
+export const listResourceDomainMembersResponseSchema = Schema.Struct({
+    items: Schema.Array(resourceDomainMemberSchema),
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    nextCursor: Schema.optional(Schema.String),
+});
 export class ResourceDomainForbiddenError extends Schema.TaggedError()("ResourceDomainForbiddenError", { message: Schema.String }, { httpApiStatus: 403 }) {
 }
 export class ResourceDomainNotFoundError extends Schema.TaggedError()("ResourceDomainNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
 }
+/** The person a member route names does not exist (the domain does). */
+export class ResourceDomainPersonNotFoundError extends Schema.TaggedError()("ResourceDomainPersonNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+/** The person exists, and the application has made no decision about them in the domain. */
+export class ResourceDomainMemberNotFoundError extends Schema.TaggedError()("ResourceDomainMemberNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+/**
+ * A decision at least as new stands, so this one changed nothing. `current` is the decision that
+ * stands; the message quotes nothing the request sent.
+ */
+export class ResourceDomainMemberVersionConflictError extends Schema.TaggedError()("ResourceDomainMemberVersionConflictError", {
+    message: Schema.String,
+    current: Schema.Struct({ state: MemberState, version: MemberVersion }),
+}, { httpApiStatus: 409 }) {
+}
 export class ResourceDomainInternalServerError extends Schema.TaggedError()("ResourceDomainInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
 }
+const memberParams = Schema.Struct({ resourceDomainId: ResourceDomainId, userId: PersonId });
+const memberErrors = [
+    ResourceDomainForbiddenError,
+    ResourceDomainNotFoundError,
+    ResourceDomainPersonNotFoundError,
+    ResourceDomainMemberVersionConflictError,
+    ResourceDomainInternalServerError,
+];
 export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
     .add(HttpApiEndpoint.post("ensureResourceDomain", "/", {
     payload: ensureResourceDomainRequestSchema,
@@ -56,6 +114,39 @@ export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
         ResourceDomainNotFoundError,
         ResourceDomainInternalServerError,
     ],
+}))
+    .add(HttpApiEndpoint.post("grantResourceDomainMember", "/:resourceDomainId/members/:userId/grant", {
+    params: memberParams,
+    payload: resourceDomainMemberDecisionSchema,
+    success: resourceDomainMemberSchema,
+    error: memberErrors,
+}))
+    .add(HttpApiEndpoint.post("revokeResourceDomainMember", "/:resourceDomainId/members/:userId/revoke", {
+    params: memberParams,
+    payload: resourceDomainMemberDecisionSchema,
+    success: resourceDomainMemberSchema,
+    error: memberErrors,
+}))
+    .add(HttpApiEndpoint.get("getResourceDomainMember", "/:resourceDomainId/members/:userId", {
+    params: memberParams,
+    success: resourceDomainMemberSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainPersonNotFoundError,
+        ResourceDomainMemberNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.get("listResourceDomainMembers", "/:resourceDomainId/members", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    query: listResourceDomainMembersQuerySchema,
+    success: listResourceDomainMembersResponseSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
 }))
     .annotate(HttpApi.PayloadParseOptions, { onExcessProperty: "error" })
     .annotate(OpenApi.Description, "Owners that are projects, not people: they never hold a login or a provider credential.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.40.0-next.769",
+  "version": "0.40.0-next.770",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "ab6f8d9ccf2f282c542e388b994099cae91c1354",
+  "gitHead": "1e8b4f1153f5107504649c863c305cd31f424d58",
   "publishConfig": {
     "access": "public"
   }