import { withRequestOptions, type StripeOpError } from "@distilled.cloud/stripe";
import {
DeleteAccountPerson,
GetAccounts,
GetAccountPersons,
GetAccountPerson,
CreateAccountPerson,
UpdateAccountPerson,
type Account as StripeAccount,
type Person as StripePerson,
type PersonRelationship,
type CreateAccountPersonRequestRelationship,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import {
alchemyMetadataKeys,
createInternalMetadata,
diffMetadata,
hasAlchemyMetadata,
stripInternalMetadata,
toMetadata,
} from "./Metadata.ts";
import { isMissingStripeResource } from "./missing.ts";
import type { Providers } from "./Providers.ts";
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;
const LIST_CONCURRENCY = 10;
export interface AccountPersonRelationship {
/**
* Whether the person is the authorizer of the account's representative.
*/
authorizer?: boolean;
/**
* Whether the person is a director of the account's legal entity.
*/
director?: boolean;
/**
* Whether the person has significant responsibility to control, manage,
* or direct the organization.
*/
executive?: boolean;
/**
* Whether the person is the legal guardian of the account's
* representative.
*/
legalGuardian?: boolean;
/**
* Whether the person is an owner of the account's legal entity.
*/
owner?: boolean;
/**
* The percent owned by the person of the account's legal entity.
*/
percentOwnership?: number;
/**
* Whether the person is authorized as the primary representative of the
* account. There can only be one representative at a time.
*/
representative?: boolean;
/**
* The person's title (e.g. CEO, Support Engineer).
*/
title?: string;
}
export interface AccountPersonProps {
/**
* Id of the Connect account this person belongs to (`acct_…`).
* Changing it replaces the person.
*/
account: string;
/**
* The person's first name.
*/
firstName?: string;
/**
* The person's last name.
*/
lastName?: string;
/**
* The person's email address.
*/
email?: string;
/**
* The person's phone number.
*/
phone?: string;
/**
* The relationship this person has with the account's legal entity.
*/
relationship?: AccountPersonRelationship;
/**
* User-defined metadata. Alchemy ownership keys (`alchemy_stack` /
* `alchemy_stage` / `alchemy_id`) are merged in automatically. Keys may
* not contain `:`.
*/
metadata?: Record<string, string>;
}
export type AccountPerson = Resource<
"Stripe.AccountPerson",
AccountPersonProps,
{
/** Stripe person id (`person_…`). */
id: string;
/** Id of the Connect account this person belongs to (`acct_…`). */
account: string;
/** The person's first name, if set. */
firstName: string | undefined;
/** The person's last name, if set. */
lastName: string | undefined;
/** The person's email address, if set. */
email: string | undefined;
/** The person's phone number, if set. */
phone: string | undefined;
/** Relationship to the account's legal entity, if set. */
relationship: AccountPersonRelationship | undefined;
/** User-defined metadata (Alchemy ownership keys stripped). */
metadata: Record<string, string>;
/** Unix timestamp when the person was created. */
created: number;
},
never,
Providers
>;
/**
* A Stripe Person on a Connect account — a director, executive, owner, or
* representative of the account's legal entity. Name, email, phone,
* relationship, and metadata update in place. Changing `account` replaces
* the person. Destroy deletes the person (the account opener cannot be
* deleted).
*
* @see https://docs.stripe.com/api/persons
*
* ### Creating a Person
* **Example:** Director on a Connect account
* ```typescript
* const person = yield* Stripe.AccountPerson("cfo", {
* account: account.id,
* firstName: "Jane",
* lastName: "Diaz",
* email: "jane.diaz@example.com",
* relationship: { director: true, title: "CFO" },
* });
* ```
*
* **Example:** Owner with metadata
* ```typescript
* const person = yield* Stripe.AccountPerson("owner", {
* account: account.id,
* firstName: "Alex",
* lastName: "Kim",
* relationship: { owner: true, percentOwnership: 25 },
* metadata: { role: "beneficial-owner" },
* });
* ```
*
* ### Updating a Person
* **Example:** Change email and title
* ```typescript
* const person = yield* Stripe.AccountPerson("cfo", {
* account: account.id,
* firstName: "Jane",
* lastName: "Diaz",
* email: "jane.diaz+updated@example.com",
* relationship: { director: true, title: "COO" },
* });
* ```
*
* @resource
* @product Account
*/
export const AccountPerson = Resource<AccountPerson>("Stripe.AccountPerson");
type AccountPersonAttributes = AccountPerson["Attributes"];
const userMetadata = (
metadata: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalMetadata(tagRecord(metadata));
const fromRelationship = (
relationship: PersonRelationship | undefined,
): AccountPersonRelationship | undefined => {
if (relationship === undefined) return undefined;
const value: AccountPersonRelationship = {
...(relationship.authorizer != null ? { authorizer: relationship.authorizer } : {}),
...(relationship.director != null ? { director: relationship.director } : {}),
...(relationship.executive != null ? { executive: relationship.executive } : {}),
...(relationship.legal_guardian != null ? { legalGuardian: relationship.legal_guardian } : {}),
...(relationship.owner != null ? { owner: relationship.owner } : {}),
...(relationship.percent_ownership != null
? { percentOwnership: relationship.percent_ownership }
: {}),
...(relationship.representative != null ? { representative: relationship.representative } : {}),
...(relationship.title != null ? { title: relationship.title } : {}),
};
return Object.keys(value).length === 0 ? undefined : value;
};
const toRelationshipWire = (
relationship: AccountPersonRelationship,
): CreateAccountPersonRequestRelationship => ({
...(relationship.authorizer !== undefined ? { authorizer: relationship.authorizer } : {}),
...(relationship.director !== undefined ? { director: relationship.director } : {}),
...(relationship.executive !== undefined ? { executive: relationship.executive } : {}),
...(relationship.legalGuardian !== undefined
? { legal_guardian: relationship.legalGuardian }
: {}),
...(relationship.owner !== undefined ? { owner: relationship.owner } : {}),
...(relationship.percentOwnership !== undefined
? { percent_ownership: relationship.percentOwnership }
: {}),
...(relationship.representative !== undefined
? { representative: relationship.representative }
: {}),
...(relationship.title !== undefined ? { title: relationship.title } : {}),
});
const sameFlag = (desired: boolean | undefined, observed: boolean | null | undefined): boolean => {
if (desired === undefined) return true;
return (observed ?? false) === desired;
};
const relationshipChanged = (
desired: AccountPersonRelationship | undefined,
observed: PersonRelationship | undefined,
): boolean => {
if (desired === undefined) return false;
if (!sameFlag(desired.authorizer, observed?.authorizer)) return true;
if (!sameFlag(desired.director, observed?.director)) return true;
if (!sameFlag(desired.executive, observed?.executive)) return true;
if (!sameFlag(desired.legalGuardian, observed?.legal_guardian)) return true;
if (!sameFlag(desired.owner, observed?.owner)) return true;
if (
desired.percentOwnership !== undefined &&
observed?.percent_ownership !== desired.percentOwnership
) {
return true;
}
if (!sameFlag(desired.representative, observed?.representative)) return true;
if (desired.title !== undefined && (observed?.title ?? "") !== desired.title) {
return true;
}
return false;
};
const toAttrs = (account: string, person: StripePerson): AccountPersonAttributes => ({
id: person.id,
account: person.account ?? account,
firstName: person.first_name ?? undefined,
lastName: person.last_name ?? undefined,
email: person.email ?? undefined,
phone: person.phone ?? undefined,
relationship: fromRelationship(person.relationship),
metadata: userMetadata(person.metadata),
created: person.created,
});
const isMissing = isMissingStripeResource;
const isSkippedListError = (error: StripeOpError): boolean =>
isMissing(error) || error._tag === "InvalidRequestError" || error._tag === "Forbidden";
const getById = (account: string, person: string) =>
GetAccountPerson({ account, person }).pipe(Effect.catchIf(isMissing, () => Effect.undefined));
const listPersons = Effect.fn(function* (account: string) {
const people: StripePerson[] = [];
let startingAfter: string | undefined;
for (let page = 0; page < LIST_MAX_PAGES; page++) {
const response = yield* GetAccountPersons({
account,
limit: LIST_PAGE_SIZE,
...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
}).pipe(Effect.catchIf(isSkippedListError, () => Effect.undefined));
if (response === undefined) {
break;
}
people.push(...response.data);
if (!response.has_more || response.data.length === 0) {
break;
}
startingAfter = response.data[response.data.length - 1]?.id;
if (startingAfter === undefined) {
break;
}
}
return people;
});
const listAllAccounts = Effect.fn(function* () {
const accounts: StripeAccount[] = [];
let startingAfter: string | undefined;
for (let page = 0; page < LIST_MAX_PAGES; page++) {
const response = yield* GetAccounts({
limit: LIST_PAGE_SIZE,
...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
});
accounts.push(...response.data);
if (!response.has_more || response.data.length === 0) {
break;
}
startingAfter = response.data[response.data.length - 1]?.id;
if (startingAfter === undefined) {
break;
}
}
return accounts;
});
const findByAlchemyIdOnAccount = Effect.fn(function* (account: string, id: string) {
const people = yield* listPersons(account);
const matches: StripePerson[] = [];
for (const person of people) {
if (yield* hasAlchemyMetadata(id, tagRecord(person.metadata))) {
matches.push(person);
}
}
matches.sort((a, b) => b.created - a.created);
return matches[0];
});
const findByAlchemyId = Effect.fn(function* (id: string) {
const accounts = yield* listAllAccounts();
const matches = yield* Effect.forEach(
accounts,
(account) => findByAlchemyIdOnAccount(account.id, id),
{ concurrency: LIST_CONCURRENCY },
);
const found = matches.filter((person): person is StripePerson => person !== undefined);
found.sort((a, b) => b.created - a.created);
return found[0];
});
const observe = Effect.fn(function* (input: { account?: string; id?: string; logicalId: string }) {
if (input.account !== undefined && input.id !== undefined) {
const byId = yield* getById(input.account, input.id);
if (byId !== undefined) return byId;
}
if (input.account !== undefined) {
const onAccount = yield* findByAlchemyIdOnAccount(input.account, input.logicalId);
if (onAccount !== undefined) return onAccount;
}
return yield* findByAlchemyId(input.logicalId);
});
const desiredMetadata = Effect.fn(function* (
id: string,
metadata: Record<string, string> | undefined,
) {
return {
...toMetadata(metadata),
...(yield* createInternalMetadata(id)),
};
});
const shouldReplace = (
news: AccountPersonProps,
output: AccountPersonAttributes | undefined,
): boolean => {
if (output === undefined) return false;
return news.account !== output.account;
};
export const AccountPersonProvider = () =>
Provider.succeed(AccountPerson, {
stables: ["id", "account", "created"],
nuke: { dependsOn: ["Stripe.Account"] },
diff: Effect.fn(function* ({ news, output }) {
if (!isResolved(news)) return undefined;
if (shouldReplace(news, output)) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const account =
output?.account ?? (typeof olds?.account === "string" ? olds.account : undefined);
const existing = yield* observe({
account,
id: output?.id,
logicalId: id,
});
if (existing === undefined) return undefined;
const resolvedAccount = existing.account ?? account;
if (resolvedAccount === undefined) return undefined;
const attrs = toAttrs(resolvedAccount, existing);
return (yield* hasAlchemyMetadata(id, tagRecord(existing.metadata))) ? attrs : Unowned(attrs);
}),
list: Effect.fn(function* () {
const accounts = yield* listAllAccounts();
const rows = yield* Effect.forEach(
accounts,
(account) =>
listPersons(account.id).pipe(
Effect.map((people) =>
people
.filter(
(person) => tagRecord(person.metadata)[alchemyMetadataKeys.stack] !== undefined,
)
.map((person) => toAttrs(account.id, person)),
),
),
{ concurrency: LIST_CONCURRENCY },
);
return rows.flat();
}),
reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
const metadata = yield* desiredMetadata(id, news.metadata);
const desiredFirstName = news.firstName ?? "";
const desiredLastName = news.lastName ?? "";
const desiredEmail = news.email ?? "";
const desiredPhone = news.phone ?? "";
let current: StripePerson | undefined = yield* observe({
account: news.account,
id: output?.id,
logicalId: id,
});
if (current !== undefined && shouldReplace(news, toAttrs(news.account, current))) {
current = undefined;
}
if (current === undefined) {
current = yield* CreateAccountPerson({
account: news.account,
...(desiredFirstName.length > 0 ? { first_name: desiredFirstName } : {}),
...(desiredLastName.length > 0 ? { last_name: desiredLastName } : {}),
...(desiredEmail.length > 0 ? { email: desiredEmail } : {}),
...(desiredPhone.length > 0 ? { phone: desiredPhone } : {}),
...(news.relationship !== undefined
? { relationship: toRelationshipWire(news.relationship) }
: {}),
metadata,
}).pipe(
withRequestOptions({
idempotencyKey: `alchemy-account-person-${instanceId}`,
}),
);
}
const observedMetadata = tagRecord(current.metadata);
const { upsert, removed } = diffMetadata(observedMetadata, metadata);
const metadataChanged = upsert.length > 0 || removed.length > 0;
const firstNameChanged = (current.first_name ?? "") !== desiredFirstName;
const lastNameChanged = (current.last_name ?? "") !== desiredLastName;
const emailChanged = (current.email ?? "") !== desiredEmail;
const phoneChanged = (current.phone ?? "") !== desiredPhone;
const relChanged = relationshipChanged(news.relationship, current.relationship);
if (
!firstNameChanged &&
!lastNameChanged &&
!emailChanged &&
!phoneChanged &&
!relChanged &&
!metadataChanged
) {
return toAttrs(news.account, current);
}
const updated = yield* UpdateAccountPerson({
account: news.account,
person: current.id,
...(firstNameChanged ? { first_name: desiredFirstName } : {}),
...(lastNameChanged ? { last_name: desiredLastName } : {}),
...(emailChanged ? { email: desiredEmail } : {}),
...(phoneChanged ? { phone: desiredPhone } : {}),
...(relChanged && news.relationship !== undefined
? { relationship: toRelationshipWire(news.relationship) }
: {}),
...(metadataChanged
? {
metadata: {
...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
...Object.fromEntries(removed.map((key) => [key, ""])),
},
}
: {}),
});
return toAttrs(news.account, updated);
}),
delete: Effect.fn(function* ({ output }) {
yield* DeleteAccountPerson({
account: output.account,
person: output.id,
}).pipe(Effect.catchIf(isMissing, () => Effect.void));
}),
});