import * as resourceSharing from "@distilled.cloud/cloudflare/resource-sharing";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
const TypeId = "Cloudflare.ResourceSharing.ShareRecipient" as const;
type TypeId = typeof TypeId;
/**
* Association status of a share recipient. Association is eventually
* consistent — a new recipient transitions `associating → associated`.
*/
export type ShareRecipientAssociationStatus =
| "associating"
| "associated"
| "disassociating"
| "disassociated";
export type ShareRecipientProps = {
/**
* The share the recipient is added to. Changing the share triggers a
* replacement.
*/
shareId: string;
/**
* Recipient account identifier. Exactly one of `accountId` /
* `organizationId` must be set. Changing it triggers a replacement.
*/
accountId?: string;
/**
* Recipient organization identifier. Exactly one of `accountId` /
* `organizationId` must be set. Changing it triggers a replacement.
*/
organizationId?: string;
};
export type ShareRecipientAttributes = {
/**
* Share recipient identifier tag. Stable for the life of the recipient.
*/
recipientId: string;
/**
* The Cloudflare account that owns (sends) the share.
*/
accountId: string;
/**
* The share the recipient belongs to.
*/
shareId: string;
/**
* The recipient account identifier reported by Cloudflare.
*/
recipientAccountId: string;
/**
* Association status of the recipient. Eventually consistent —
* `associating` settles to `associated`.
*/
associationStatus: ShareRecipientAssociationStatus;
/**
* When the recipient was created.
*/
created: string;
/**
* When the recipient was last modified.
*/
modified: string;
};
export type ShareRecipient = Resource<
TypeId,
ShareRecipientProps,
ShareRecipientAttributes,
never,
Providers
>;
/**
* A recipient on an existing Cloudflare share — grants another account or
* organization access to the share's resources.
*
* This is an existence-only resource: there is no update API, so every prop
* change triggers a replacement. Association is eventually consistent
* (`associating → associated`). Do not manage the same recipient both inline
* on `Share.recipients` and through this resource.
* ### Adding a Recipient
* **Example:** Share with another account
* ```typescript
* const recipient = yield* Cloudflare.ResourceSharing.ShareRecipient("Partner", {
* shareId: share.shareId,
* accountId: "<recipient-account-id>",
* });
* ```
*
* **Example:** Share with an organization
* ```typescript
* const recipient = yield* Cloudflare.ResourceSharing.ShareRecipient("Org", {
* shareId: share.shareId,
* organizationId: "<recipient-organization-id>",
* });
* ```
*
* @see https://developers.cloudflare.com/fundamentals/manage-account-resources/
*
* @resource
* @product Resource Sharing
* @category Account & Identity
*/
export const ShareRecipient = Resource<ShareRecipient>(TypeId);
/**
* Returns true if the given value is a ShareRecipient resource.
*/
export const isShareRecipient = (value: unknown): value is ShareRecipient =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const ShareRecipientProvider = () =>
Provider.succeed(ShareRecipient, {
stables: ["recipientId", "accountId", "shareId", "recipientAccountId", "created"],
diff: Effect.fn(function* ({ olds, news, output }) {
if (!isResolved(news)) return undefined;
const { accountId } = yield* yield* CloudflareEnvironment;
if ((output?.accountId ?? accountId) !== accountId) {
return { action: "replace" } as const;
}
// No update API — every identity change is a replacement. By diff
// time both sides are resolved strings.
const oldShareId = output?.shareId ?? olds?.shareId;
if (
typeof oldShareId === "string" &&
typeof news.shareId === "string" &&
oldShareId !== news.shareId
) {
return { action: "replace" } as const;
}
const oldTarget =
output?.recipientAccountId ??
(olds?.accountId as string | undefined) ??
(olds?.organizationId as string | undefined);
const newTarget =
(news.accountId as string | undefined) ?? (news.organizationId as string | undefined);
if (
typeof oldTarget === "string" &&
typeof newTarget === "string" &&
oldTarget !== newTarget
) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ olds, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
const shareId = output?.shareId ?? (olds?.shareId as string | undefined);
if (shareId === undefined) return undefined;
if (output?.recipientId) {
const observed = yield* getRecipient(acct, shareId, output.recipientId);
return observed ? toAttributes(observed, acct, shareId) : undefined;
}
// Cold read — recover from lost state by matching the recipient
// account/organization id among the share's recipients.
const target =
(olds?.accountId as string | undefined) ?? (olds?.organizationId as string | undefined);
if (target === undefined) return undefined;
const match = yield* findRecipient(acct, shareId, target);
return match ? toAttributes(match, acct, shareId) : undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
const shareId = news.shareId as string;
const targetAccountId = news.accountId as string | undefined;
const targetOrganizationId = news.organizationId as string | undefined;
// Observe — the recipientId cached on `output` is a hint; fall
// through to a natural-key lookup so an AlreadyExists race converges
// instead of failing, then to create. Existence-only resource: there
// is no sync step.
const observed =
(output?.recipientId
? yield* getRecipient(acct, shareId, output.recipientId)
: undefined) ??
(yield* findRecipient(acct, shareId, targetAccountId ?? targetOrganizationId ?? ""));
if (observed) {
return toAttributes(observed, acct, shareId);
}
// Ensure — greenfield (or out-of-band delete).
const created = yield* resourceSharing.createRecipient({
accountId: acct,
shareId,
recipientAccountId: targetAccountId,
organizationId: targetOrganizationId,
});
return toAttributes(created, acct, shareId);
}),
delete: Effect.fn(function* ({ output }) {
// Disassociation is eventually consistent; the DELETE call is
// idempotent against a missing recipient.
yield* resourceSharing
.deleteRecipient({
accountId: output.accountId,
shareId: output.shareId,
recipientId: output.recipientId,
})
.pipe(Effect.catchTag("ShareRecipientNotFound", () => Effect.void));
}),
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Parent fan-out: recipients are keyed by their parent Share, which is
// account-scoped. Enumerate the account's owned (sent) shares, then list
// recipients within each share with bounded concurrency.
const shareIds = yield* resourceSharing.listResourceSharings
.pages({ accountId, kind: "sent" })
.pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) => (page.result ?? []).map((share) => share.id)),
),
// The account cannot enumerate shares — nothing to list.
Effect.catchTag("Forbidden", () => Effect.succeed([] as string[])),
);
const rows = yield* Effect.forEach(
shareIds,
(shareId) =>
resourceSharing.listRecipients.pages({ accountId, shareId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? [])
// Disassociated recipients are "gone" — match `read`.
.filter((r) => r.associationStatus !== "disassociated")
.map((r) => toAttributes(r, accountId, shareId)),
),
),
// The share vanished mid-enumeration or isn't ours — skip it.
Effect.catchTag(["ShareNotFound", "Forbidden"], () =>
Effect.succeed([] as ShareRecipientAttributes[]),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
type ObservedRecipient = resourceSharing.GetRecipientResponse;
/**
* Read a recipient by id, mapping "gone" (`ShareRecipientNotFound`, HTTP
* 404) and the terminal `disassociated` status to `undefined`.
*/
const getRecipient = (accountId: string, shareId: string, recipientId: string) =>
resourceSharing.getRecipient({ accountId, shareId, recipientId }).pipe(
Effect.map((recipient): ObservedRecipient | undefined =>
recipient.associationStatus === "disassociated" ? undefined : recipient,
),
Effect.catchTag("ShareRecipientNotFound", () => Effect.undefined),
);
/**
* Find a live recipient by its account/organization id. A missing share
* surfaces as `ShareNotFound` — treat it as "no recipient".
*/
const findRecipient = (accountId: string, shareId: string, target: string) =>
resourceSharing.listRecipients.items({ accountId, shareId, perPage: 50 }).pipe(
Stream.filter((r) => r.accountId === target && r.associationStatus !== "disassociated"),
Stream.runHead,
Effect.map(Option.getOrUndefined),
Effect.catchTag("ShareNotFound", () => Effect.undefined),
);
const toAttributes = (
recipient:
| ObservedRecipient
| resourceSharing.CreateRecipientResponse
| resourceSharing.ListRecipientsResponse["result"][number],
accountId: string,
shareId: string,
): ShareRecipientAttributes => ({
recipientId: recipient.id,
accountId,
shareId,
recipientAccountId: recipient.accountId,
// Distilled widens generated string enums to open unions (`string & {}`).
associationStatus: recipient.associationStatus as ShareRecipientAssociationStatus,
created: recipient.created,
modified: recipient.modified,
});