@shuffl/api-contracts 0.4.0 → 0.5.1

package/dist/schemas.js

@@ -156,7 +156,8 @@ export const matchSchema = z
     maxGroupSize: z.number().int().min(2).max(8),
     strategy: strategySchema,
     unitIds: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
-    unitKind: z.enum(['department', 'team']).optional(),
+    // #745: communities mix like teams people choose themselves.
+    unitKind: z.enum(['department', 'team', 'community']).optional(),
 })
     .refine((x) => !currentStrategies.includes(x.strategy) || x.iterations <= 50, 'Purpose matching supports at most 50 search attempts')
     .refine((x) => x.maxGroupSize >= x.groupSize, 'Maximum group size must be at least the target size')
@@ -168,7 +169,7 @@ export const matchSchema = z
     .refine((x) => !x.unitIds || new Set(x.unitIds).size === x.unitIds.length, 'Choose each team or department only once')
     .refine((x) => x.strategy === 'cross-unit' || x.strategy === 'within-unit'
     ? !!x.unitKind
-    : x.unitKind === undefined, 'Choose teams or departments only when mixing across or within them')
+    : x.unitKind === undefined, 'Choose teams, departments or communities only when mixing across or within them')
     .refine((x) => !currentStrategies.includes(x.strategy) ||
     x.maxGroupSize <= x.groupSize + 1, 'Allow at most one extra person per group')
     .refine((x) => !x.keepApart || currentStrategies.includes(x.strategy), 'Keeping coworkers apart needs a current matching purpose')
@@ -176,6 +177,17 @@ export const matchSchema = z
 export const programInput = z.object({
     channelId: z.string().regex(/^[CG][A-Z0-9]+$/),
     channelName: z.string().trim().min(1).max(100),
+    // #745: one to 20 communities whose members take part instead, by those
+    // who show the community on their profile. Empty or omitted means the
+    // channel or the group; a program uses one of the three.
+    communityIds: z
+        .array(z.string().trim().min(1).max(128))
+        .max(20)
+        .optional()
+        .describe('Communities whose members take part, instead of the Slack channel or a group. Only people who show the community on their profile are enrolled.'),
+    // #1832: the group whose members take part; null or omitted means everyone
+    // in the Slack channel. Introductions are posted in the channel either way.
+    groupId: z.string().trim().min(1).max(128).nullish(),
     includeBios: z.boolean(),
     // Omission preserves an existing program's choice; new programs default on.
     includeSchedulingLink: z.boolean().optional(),
@@ -201,6 +213,8 @@ export const profileSchema = z.object({
 export const programPatch = z.strictObject({
     channelId: programInput.shape.channelId.optional(),
     channelName: programInput.shape.channelName.optional(),
+    communityIds: z.array(z.string().trim().min(1).max(128)).max(20).optional(),
+    groupId: z.string().trim().min(1).max(128).nullable().optional(),
     includeBios: z.boolean().optional(),
     includeSchedulingLink: z.boolean().optional(),
     intro: programInput.shape.intro.optional(),
@@ -218,7 +232,10 @@ export const programPatch = z.strictObject({
         maxGroupSize: z.number().int().min(2).max(8).optional(),
         strategy: strategySchema.optional(),
         unitIds: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
-        unitKind: z.enum(['department', 'team']).nullable().optional(),
+        unitKind: z
+            .enum(['department', 'team', 'community'])
+            .nullable()
+            .optional(),
     })
         .optional(),
     name: programInput.shape.name.optional(),

package/dist/webhooks.d.ts

@@ -0,0 +1,373 @@
+export declare const webhookApiVersion = "2026-10-17";
+export declare const webhookEventGroups: {
+    readonly connections: {
+        readonly description: 'Connections programs, rounds and who takes part';
+        readonly label: 'Connections';
+        readonly scope: 'programs:read';
+    };
+    readonly hr: {
+        readonly description: 'Who answers HR requests';
+        readonly label: 'HR team';
+        readonly scope: 'hr:read';
+    };
+    readonly knowledge: {
+        readonly description: 'Proposals, drafts, published pages and connected sources';
+        readonly label: 'Knowledge';
+        readonly scope: 'knowledge:read';
+    };
+    readonly people: {
+        readonly description: 'People, roles, access, identities and departments';
+        readonly label: 'People';
+        readonly scope: 'users:read';
+    };
+    readonly playbook: {
+        readonly description: 'Playbook enrollments, steps, buddies and check-ins';
+        readonly label: 'Playbooks';
+        readonly scope: 'playbooks:read';
+    };
+    readonly webhooks: {
+        readonly description: 'Test events and endpoints Shuffl turned off';
+        readonly label: 'Webhooks';
+        readonly scope: 'webhooks:read';
+    };
+    readonly workspace: {
+        readonly description: 'The workspace itself and its Slack connection';
+        readonly label: 'Workspace';
+        readonly scope: 'team:read';
+    };
+};
+export type WebhookEventGroup = keyof typeof webhookEventGroups;
+export declare const webhookEventGroupIds: WebhookEventGroup[];
+export declare const webhookEventCatalog: {
+    readonly 'hr.responder.granted': {
+        readonly description: 'Someone joined the HR team that answers requests';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'hr';
+    };
+    readonly 'hr.responder.revoked': {
+        readonly description: 'Someone left the HR team';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'hr';
+    };
+    readonly 'hr.team.renamed': {
+        readonly description: 'The HR team’s name changed';
+        readonly fields: readonly ["revision"];
+        readonly group: 'hr';
+    };
+    readonly 'knowledge.document.archived': {
+        readonly description: 'A page was archived';
+        readonly fields: readonly ["document_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.document.audience_changed': {
+        readonly description: 'Who can read a published page changed';
+        readonly fields: readonly ["document_id", "version_id", "audience", "previous_audience"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.document.published': {
+        readonly description: 'A page was published';
+        readonly fields: readonly ["document_id", "version_id", "audience"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.document.restored': {
+        readonly description: 'An archived page was restored';
+        readonly fields: readonly ["document_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.document.withdrawn': {
+        readonly description: 'A published page was withdrawn';
+        readonly fields: readonly ["document_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.draft.saved': {
+        readonly description: 'A draft of a page was saved';
+        readonly fields: readonly ["document_id", "version_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.proposal.created': {
+        readonly description: 'Mello proposed new or changed Knowledge for review';
+        readonly fields: readonly ["proposal_id", "revision"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.proposal.published': {
+        readonly description: 'A verifier approved a proposal, as written or edited';
+        readonly fields: readonly ["proposal_id", "revision", "document_id", "edited"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.proposal.rejected': {
+        readonly description: 'A verifier turned a proposal down';
+        readonly fields: readonly ["proposal_id", "revision"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.section.removed': {
+        readonly description: 'A section was removed from a handbook page';
+        readonly fields: readonly ["document_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.source.access_lost': {
+        readonly description: 'Shuffl can no longer read a connected document';
+        readonly fields: readonly ["document_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.source.connected': {
+        readonly description: 'A Knowledge source such as Google Drive was connected';
+        readonly fields: readonly ["connection_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.source.disconnected': {
+        readonly description: 'A Knowledge source was disconnected';
+        readonly fields: readonly ["connection_id"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.verifier.granted': {
+        readonly description: 'Someone can now verify Knowledge';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'knowledge';
+    };
+    readonly 'knowledge.verifier.revoked': {
+        readonly description: 'Someone can no longer verify Knowledge';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'knowledge';
+    };
+    readonly 'participant.opted_in': {
+        readonly description: 'A person joined a Connections program';
+        readonly fields: readonly ["person_id", "program_id", "revision"];
+        readonly group: 'connections';
+    };
+    readonly 'participant.opted_out': {
+        readonly description: 'A person left a Connections program';
+        readonly fields: readonly ["person_id", "program_id", "revision"];
+        readonly group: 'connections';
+    };
+    readonly 'participant.profile_updated': {
+        readonly description: 'A person updated their profile';
+        readonly fields: readonly ["person_id"];
+        readonly group: 'connections';
+    };
+    readonly 'person.access_changed': {
+        readonly description: 'A person’s app access or employment changed';
+        readonly fields: readonly ["person_id", "status", "previous_status", "employment", "previous_employment", "revision"];
+        readonly group: 'people';
+    };
+    readonly 'person.access_suspended': {
+        readonly description: 'A person’s access was suspended';
+        readonly fields: readonly ["person_id"];
+        readonly group: 'people';
+    };
+    readonly 'person.created': {
+        readonly description: 'A person was added to the directory';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'people';
+    };
+    readonly 'person.identity_linked': {
+        readonly description: 'A Slack or single sign-on identity was linked to a person';
+        readonly fields: readonly ["person_id", "identity_id", "provider"];
+        readonly group: 'people';
+    };
+    readonly 'person.identity_revoked': {
+        readonly description: 'A linked identity was removed from a person';
+        readonly fields: readonly ["person_id", "identity_id", "provider"];
+        readonly group: 'people';
+    };
+    readonly 'person.manager_changed': {
+        readonly description: 'A person’s manager changed';
+        readonly fields: readonly ["person_id"];
+        readonly group: 'people';
+    };
+    readonly 'person.role_changed': {
+        readonly description: 'A person’s workspace role changed';
+        readonly fields: readonly ["person_id", "role", "previous_role"];
+        readonly group: 'people';
+    };
+    readonly 'person.updated': {
+        readonly description: 'A person’s directory record changed';
+        readonly fields: readonly ["person_id", "revision"];
+        readonly group: 'people';
+    };
+    readonly 'playbooks.approved': {
+        readonly description: 'HR approved a person’s playbook steps';
+        readonly fields: readonly ["enrollment_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.buddy.accepted': {
+        readonly description: 'A buddy said yes';
+        readonly fields: readonly ["enrollment_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.buddy.assigned': {
+        readonly description: 'A buddy was asked to help a new hire';
+        readonly fields: readonly ["enrollment_id", "buddy_person_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.buddy.declined': {
+        readonly description: 'A buddy said no';
+        readonly fields: readonly ["enrollment_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.check_in.answered': {
+        readonly description: 'A new hire answered a check-in: all_good, or need_help when they asked HR for help';
+        readonly fields: readonly ["step_id", "enrollment_id", "answer"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.enrolled': {
+        readonly description: 'A person started a playbook';
+        readonly fields: readonly ["enrollment_id", "person_id", "program_id", "with_buddy"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.enrollment_removed': {
+        readonly description: 'A person was taken off a playbook';
+        readonly fields: readonly ["enrollment_id", "reason"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.schedule_changed': {
+        readonly description: 'A person’s playbook schedule changed';
+        readonly fields: readonly ["enrollment_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.step.failed': {
+        readonly description: 'A playbook step could not be delivered';
+        readonly fields: readonly ["step_id", "reason"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.step.needs_review': {
+        readonly description: 'A playbook step waits for HR before it sends';
+        readonly fields: readonly ["step_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'playbooks.step.sent': {
+        readonly description: 'A playbook step reached its person';
+        readonly fields: readonly ["step_id"];
+        readonly group: 'playbook';
+    };
+    readonly 'program.archived': {
+        readonly description: 'A program was archived';
+        readonly fields: readonly ["program_id"];
+        readonly group: 'connections';
+    };
+    readonly 'program.created': {
+        readonly description: 'A Connections program or playbook was created';
+        readonly fields: readonly ["program_id", "kind"];
+        readonly group: 'connections';
+    };
+    readonly 'program.paused': {
+        readonly description: 'A program was paused';
+        readonly fields: readonly ["program_id"];
+        readonly group: 'connections';
+    };
+    readonly 'program.resumed': {
+        readonly description: 'A program was switched on';
+        readonly fields: readonly ["program_id"];
+        readonly group: 'connections';
+    };
+    readonly 'program.updated': {
+        readonly description: 'A program’s settings changed';
+        readonly fields: readonly ["program_id", "kind"];
+        readonly group: 'connections';
+    };
+    readonly 'round.planned': {
+        readonly description: 'Shuffl planned a round of introductions';
+        readonly fields: readonly ["round_id", "groups", "unmatched"];
+        readonly group: 'connections';
+    };
+    readonly 'round.requested': {
+        readonly description: 'Someone asked for a round of introductions';
+        readonly fields: readonly ["round_id", "retry"];
+        readonly group: 'connections';
+    };
+    readonly 'slack.connected': {
+        readonly description: 'Slack was connected';
+        readonly fields: readonly [];
+        readonly group: 'workspace';
+    };
+    readonly 'slack.connection_expired': {
+        readonly description: 'Slack stopped accepting Shuffl’s connection';
+        readonly fields: readonly ["reason"];
+        readonly group: 'workspace';
+    };
+    readonly 'slack.uninstalled': {
+        readonly description: 'Shuffl was removed from Slack';
+        readonly fields: readonly ["reason"];
+        readonly group: 'workspace';
+    };
+    readonly 'webhook.endpoint.disabled': {
+        readonly description: 'Shuffl turned an endpoint off after it kept failing';
+        readonly fields: readonly ["endpoint_id", "reason"];
+        readonly group: 'webhooks';
+    };
+    readonly 'webhook.test': {
+        readonly description: 'A test event someone sent from Settings or the API';
+        readonly fields: readonly ["endpoint_id"];
+        readonly group: 'webhooks';
+    };
+    readonly 'workspace.deletion_requested': {
+        readonly description: 'An owner asked to delete the workspace';
+        readonly fields: readonly ["delete_after"];
+        readonly group: 'workspace';
+    };
+    readonly 'workspace.exported': {
+        readonly description: 'Someone exported the workspace’s data';
+        readonly fields: readonly [];
+        readonly group: 'workspace';
+    };
+    readonly 'workspace.renamed': {
+        readonly description: 'The workspace was renamed';
+        readonly fields: readonly [];
+        readonly group: 'workspace';
+    };
+    readonly 'workspace.restored': {
+        readonly description: 'The workspace was restored';
+        readonly fields: readonly ["deletion_canceled"];
+        readonly group: 'workspace';
+    };
+    readonly 'workspace.slack_join_access_changed': {
+        readonly description: 'Who can join from Slack changed';
+        readonly fields: readonly [];
+        readonly group: 'workspace';
+    };
+};
+export type WebhookEventType = keyof typeof webhookEventCatalog;
+export declare const webhookEventTypes: WebhookEventType[];
+export declare const isWebhookEventType: (value: string) => value is WebhookEventType;
+/** Keys no payload may ever carry. A test walks the catalog against it. */
+export declare const webhookNeverSendFields: readonly ['answer_text', 'body', 'comment', 'bio', 'email', 'feedback', 'message', 'name', 'note', 'previous_name', 'question', 'slack_team_id', 'slack_user_id', 'subject', 'text', 'title', 'token', 'secret'];
+type Fields<T extends WebhookEventType> = (typeof webhookEventCatalog)[T]['fields'][number];
+export type WebhookEventData<T extends WebhookEventType = WebhookEventType> = {
+    [K in Fields<T>]?: string | number | boolean | null;
+};
+export type WebhookActor = {
+    type: 'user' | 'system';
+    id: string | null;
+};
+export type WebhookEvent<T extends WebhookEventType = WebhookEventType> = {
+    [K in T]: {
+        id: string;
+        type: K;
+        api_version: string;
+        created_at: string;
+        workspace_id: string;
+        actor: WebhookActor;
+        data: WebhookEventData<K>;
+    };
+}[T];
+export declare const webhookSecretPrefix = "whsec_";
+export declare const webhookToleranceSeconds = 300;
+/** The `v1,<signature>` value for one secret: base64 HMAC-SHA256 of
+ * `id.timestamp.body`, as Standard Webhooks specifies. */
+export declare function signWebhook(secret: string, id: string, timestamp: number, body: string): Promise<string>;
+export declare class WebhookVerificationError extends Error {
+    name: string;
+}
+type HeaderSource = Headers | Record<string, string | string[] | undefined | null>;
+/** Checks a delivery's Standard Webhooks headers against the endpoint's
+ * signing secret (or several while one is rolled) and returns the parsed
+ * event. Pass the raw request body, before any JSON parsing. Throws
+ * WebhookVerificationError for a missing header, a timestamp more than
+ * five minutes away or a signature that matches no secret. */
+export declare function verifyWebhook<T extends WebhookEventType = WebhookEventType>(input: {
+    body: string;
+    headers: HeaderSource;
+    secret: string | readonly string[];
+    toleranceSeconds?: number;
+    now?: Date;
+}): Promise<WebhookEvent<T>>;
+export {};