71 lines
2.0 KiB
TypeScript
71 lines
2.0 KiB
TypeScript
import {
|
|
CreateEntityParamsV1Schema,
|
|
DeleteEntityParamsV0Schema,
|
|
GetEntityParamsV0Schema,
|
|
} from "@autumn/shared";
|
|
import { createJSDocDescription, example } from "../../utils/jsDocs/index.js";
|
|
|
|
export const createEntityJsDoc = createJSDocDescription({
|
|
description:
|
|
"Creates an entity for a customer and feature, then returns the entity with balances and subscriptions.",
|
|
whenToUse:
|
|
"Use entities when usage and access must be scoped to sub-resources (for example seats, projects, or workspaces) instead of only the customer.",
|
|
body: CreateEntityParamsV1Schema,
|
|
examples: [
|
|
example({
|
|
description: "Create a seat entity",
|
|
values: {
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
featureId: "seats",
|
|
name: "Seat 42",
|
|
},
|
|
}),
|
|
],
|
|
methodName: "entities.create",
|
|
returns:
|
|
"The created entity object including its current subscriptions, purchases, and balances.",
|
|
});
|
|
|
|
export const getEntityJsDoc = createJSDocDescription({
|
|
description: "Fetches an entity by its ID.",
|
|
whenToUse:
|
|
"Use this to read one entity's current state. Pass customerId when you want to scope the lookup to a specific customer.",
|
|
body: GetEntityParamsV0Schema,
|
|
examples: [
|
|
example({
|
|
description: "Fetch a seat entity",
|
|
values: {
|
|
entityId: "seat_42",
|
|
},
|
|
}),
|
|
example({
|
|
description: "Fetch a seat entity for a specific customer",
|
|
values: {
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
},
|
|
}),
|
|
],
|
|
methodName: "entities.get",
|
|
returns:
|
|
"The entity object including its current subscriptions, purchases, and balances.",
|
|
});
|
|
|
|
export const deleteEntityJsDoc = createJSDocDescription({
|
|
description: "Deletes an entity by entity ID.",
|
|
whenToUse:
|
|
"Use this when the underlying resource is removed and you no longer want entity-scoped balances or subscriptions tracked for it.",
|
|
body: DeleteEntityParamsV0Schema,
|
|
examples: [
|
|
example({
|
|
description: "Delete a seat entity",
|
|
values: {
|
|
entityId: "seat_42",
|
|
},
|
|
}),
|
|
],
|
|
methodName: "entities.delete",
|
|
returns: "A success flag indicating the entity was deleted.",
|
|
});
|