@slates/google-people-recipes 1.0.0-rc.1

package/dist/index.module.js

@@ -0,0 +1,420 @@
+// src/index.ts
+import { ServiceError, badRequestError } from "@lowerdeck/error";
+import { defineToolRecipe } from "@slates/tool-recipes";
+import { anyOf, createAxios } from "slates";
+import { z } from "zod";
+var GOOGLE_PEOPLE_API_BASE_URL = "https://people.googleapis.com/v1/";
+var peopleAxios = createAxios({
+  baseURL: GOOGLE_PEOPLE_API_BASE_URL
+});
+var googlePeopleScopes = {
+  contactsReadonly: "https://www.googleapis.com/auth/contacts.readonly"
+};
+var googlePeopleReadonlyScopes = anyOf(googlePeopleScopes.contactsReadonly);
+var DEFAULT_PERSON_FIELDS = "names,emailAddresses,phoneNumbers,addresses,organizations,birthdays,urls,biographies,events,genders,occupations,nicknames,relations,userDefined,memberships";
+var READONLY_PERSON_FIELDS = "names,emailAddresses,phoneNumbers";
+var nameSchema = z.object({
+  displayName: z.string().optional().describe("Full display name"),
+  givenName: z.string().optional().describe("First/given name"),
+  familyName: z.string().optional().describe("Last/family name"),
+  middleName: z.string().optional().describe("Middle name"),
+  prefix: z.string().optional().describe("Name prefix (e.g., Mr., Dr.)"),
+  suffix: z.string().optional().describe("Name suffix (e.g., Jr., III)")
+}).describe("Name of the contact");
+var emailSchema = z.object({
+  value: z.string().describe("Email address"),
+  type: z.string().optional().describe("Type of email (e.g., home, work, other)")
+}).describe("Email address");
+var phoneSchema = z.object({
+  value: z.string().describe("Phone number"),
+  type: z.string().optional().describe("Type of phone (e.g., home, work, mobile)")
+}).describe("Phone number");
+var addressSchema = z.object({
+  streetAddress: z.string().optional().describe("Street address"),
+  city: z.string().optional().describe("City"),
+  region: z.string().optional().describe("State or region"),
+  postalCode: z.string().optional().describe("Postal/ZIP code"),
+  country: z.string().optional().describe("Country"),
+  type: z.string().optional().describe("Type of address (e.g., home, work)")
+}).describe("Physical address");
+var organizationSchema = z.object({
+  name: z.string().optional().describe("Organization name"),
+  title: z.string().optional().describe("Job title"),
+  department: z.string().optional().describe("Department name")
+}).describe("Organization/company");
+var dateFieldSchema = z.object({
+  year: z.number().optional().describe("Year (omit for recurring events)"),
+  month: z.number().optional().describe("Month (1-12)"),
+  day: z.number().optional().describe("Day of month (1-31)")
+}).describe("Date");
+var birthdaySchema = z.object({
+  date: dateFieldSchema.optional()
+}).describe("Birthday");
+var urlSchema = z.object({
+  value: z.string().describe("URL"),
+  type: z.string().optional().describe("Type of URL (e.g., homePage, blog, profile)")
+}).describe("URL");
+var biographySchema = z.object({
+  value: z.string().describe("Biography or notes text")
+}).describe("Biography/notes");
+var customFieldSchema = z.object({
+  key: z.string().describe("Custom field label"),
+  value: z.string().describe("Custom field value")
+}).describe("Custom field");
+var nicknameSchema = z.object({
+  value: z.string().describe("Nickname")
+}).describe("Nickname");
+var relationSchema = z.object({
+  person: z.string().describe("Name of the related person"),
+  type: z.string().optional().describe("Relationship type (e.g., spouse, parent, child, friend)")
+}).describe("Relationship");
+var eventSchema = z.object({
+  date: dateFieldSchema.optional(),
+  type: z.string().optional().describe("Type of event (e.g., anniversary)")
+}).describe("Event/date");
+var occupationSchema = z.object({
+  value: z.string().describe("Occupation")
+}).describe("Occupation");
+var membershipSchema = z.object({
+  contactGroupResourceName: z.string().optional().describe("Resource name of the contact group")
+}).describe("Group membership");
+var contactInputSchema = z.object({
+  names: z.array(nameSchema).optional().describe("Names for the contact"),
+  emailAddresses: z.array(emailSchema).optional().describe("Email addresses"),
+  phoneNumbers: z.array(phoneSchema).optional().describe("Phone numbers"),
+  addresses: z.array(addressSchema).optional().describe("Physical addresses"),
+  organizations: z.array(organizationSchema).optional().describe("Organizations/companies"),
+  birthdays: z.array(birthdaySchema).optional().describe("Birthdays"),
+  urls: z.array(urlSchema).optional().describe("URLs"),
+  biographies: z.array(biographySchema).optional().describe("Biographies/notes"),
+  userDefined: z.array(customFieldSchema).optional().describe("Custom fields"),
+  nicknames: z.array(nicknameSchema).optional().describe("Nicknames"),
+  relations: z.array(relationSchema).optional().describe("Relationships"),
+  events: z.array(eventSchema).optional().describe("Events/dates"),
+  occupations: z.array(occupationSchema).optional().describe("Occupations")
+});
+var contactOutputSchema = z.object({
+  resourceName: z.string().describe("Unique resource name (e.g., people/c12345)"),
+  etag: z.string().optional().describe("ETag for concurrency control, required when updating"),
+  names: z.array(nameSchema).optional(),
+  emailAddresses: z.array(emailSchema).optional(),
+  phoneNumbers: z.array(phoneSchema).optional(),
+  addresses: z.array(addressSchema).optional(),
+  organizations: z.array(organizationSchema).optional(),
+  birthdays: z.array(birthdaySchema).optional(),
+  urls: z.array(urlSchema).optional(),
+  biographies: z.array(biographySchema).optional(),
+  userDefined: z.array(customFieldSchema).optional(),
+  nicknames: z.array(nicknameSchema).optional(),
+  relations: z.array(relationSchema).optional(),
+  events: z.array(eventSchema).optional(),
+  occupations: z.array(occupationSchema).optional(),
+  memberships: z.array(membershipSchema).optional()
+});
+var listContactsInputSchema = z.object({
+  pageSize: z.number().optional().describe("Number of contacts to return per page (max 1000, default 100)"),
+  pageToken: z.string().optional().describe("Token for fetching the next page of results"),
+  sortOrder: z.enum([
+    "LAST_MODIFIED_ASCENDING",
+    "LAST_MODIFIED_DESCENDING",
+    "FIRST_NAME_ASCENDING",
+    "LAST_NAME_ASCENDING"
+  ]).optional().describe("Sort order for the results")
+});
+var listContactsOutputSchema = z.object({
+  contacts: z.array(contactOutputSchema).describe("List of contacts"),
+  nextPageToken: z.string().optional().describe("Token for fetching the next page"),
+  totalPeople: z.number().optional().describe("Total number of contacts"),
+  totalItems: z.number().optional().describe("Total number of items in response")
+});
+var searchContactsInputSchema = z.object({
+  query: z.string().describe(
+    "Search query \u2014 matches against names, emails, phone numbers, and other contact fields"
+  ),
+  pageSize: z.number().optional().describe("Maximum number of results to return (default 30)")
+});
+var searchContactsOutputSchema = z.object({
+  contacts: z.array(contactOutputSchema).describe("Matching contacts")
+});
+var getContactInputSchema = z.object({
+  resourceName: z.string().describe('Resource name of the contact (e.g., "people/c12345" or "people/me")')
+});
+var formatContact = (person) => {
+  return {
+    resourceName: person.resourceName,
+    etag: person.etag,
+    names: person.names,
+    emailAddresses: person.emailAddresses,
+    phoneNumbers: person.phoneNumbers,
+    addresses: person.addresses,
+    organizations: person.organizations,
+    birthdays: person.birthdays,
+    urls: person.urls,
+    biographies: person.biographies,
+    userDefined: person.userDefined,
+    nicknames: person.nicknames,
+    relations: person.relations,
+    events: person.events,
+    occupations: person.occupations,
+    memberships: person.memberships?.map((membership) => ({
+      contactGroupResourceName: membership.contactGroupMembership?.contactGroupResourceName
+    }))
+  };
+};
+var isRecord = (value) => typeof value === "object" && value !== null;
+var addMessage = (messages, value) => {
+  if (typeof value !== "string") return;
+  let trimmed = value.trim();
+  if (trimmed && !messages.includes(trimmed)) {
+    messages.push(trimmed);
+  }
+};
+var collectMessages = (value, messages) => {
+  if (!isRecord(value)) {
+    addMessage(messages, value);
+    return;
+  }
+  for (let key of ["message", "error_description", "error", "detail", "reason"]) {
+    addMessage(messages, value[key]);
+  }
+  let nestedError = value.error;
+  if (isRecord(nestedError)) {
+    collectMessages(nestedError, messages);
+  }
+  let errors = value.errors;
+  if (Array.isArray(errors)) {
+    for (let item of errors) {
+      collectMessages(item, messages);
+    }
+  }
+};
+var extractGooglePeopleMessage = (error) => {
+  let response = isRecord(error) ? error.response : void 0;
+  let messages = [];
+  collectMessages(response?.data, messages);
+  if (isRecord(error)) {
+    collectMessages(error.data, messages);
+  }
+  if (messages.length > 0) {
+    return messages.join(" - ");
+  }
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return "Unknown error";
+};
+var getErrorStatus = (error) => {
+  if (!isRecord(error)) return void 0;
+  let response = error.response;
+  if (typeof response?.status === "number") return response.status;
+  if (typeof error.status === "number") return error.status;
+  if (isRecord(error.data) && typeof error.data.status === "number") return error.data.status;
+  if (isRecord(error.upstream) && typeof error.upstream.status === "number") {
+    return error.upstream.status;
+  }
+  return void 0;
+};
+var getErrorStatusText = (error) => {
+  if (!isRecord(error)) return void 0;
+  let response = error.response;
+  if (typeof response?.statusText === "string") return response.statusText;
+  if (isRecord(error.upstream) && typeof error.upstream.statusText === "string") {
+    return error.upstream.statusText;
+  }
+  return void 0;
+};
+var googlePeopleServiceError = (message) => new ServiceError(badRequestError({ message }));
+var googlePeopleApiError = (error, operation = "request") => {
+  if (error instanceof ServiceError) {
+    return error;
+  }
+  let status = getErrorStatus(error);
+  let statusText = getErrorStatusText(error);
+  let statusLabel = status !== void 0 ? `HTTP ${status}${statusText ? ` ${statusText}` : ""}: ` : "";
+  let serviceError = googlePeopleServiceError(
+    `Google People API ${operation} failed: ${statusLabel}${extractGooglePeopleMessage(error)}`
+  );
+  serviceError.data.reason = "google_people_api_error";
+  serviceError.data.upstreamStatus = status;
+  if (error instanceof Error) {
+    serviceError.setParent(error);
+  }
+  return serviceError;
+};
+var GooglePeopleClient = class {
+  constructor(config) {
+    this.config = config;
+    this.api = config.api ?? peopleAxios;
+  }
+  config;
+  api;
+  headers() {
+    return {
+      Authorization: `Bearer ${this.config.token}`
+    };
+  }
+  async getContact(resourceName, personFields) {
+    try {
+      let response = await this.api.get(resourceName, {
+        params: { personFields: personFields || DEFAULT_PERSON_FIELDS },
+        headers: this.headers()
+      });
+      return response.data;
+    } catch (error) {
+      throw googlePeopleApiError(error, "get contact");
+    }
+  }
+  async listContacts(params) {
+    try {
+      let response = await this.api.get("people/me/connections", {
+        params: {
+          personFields: params.personFields || DEFAULT_PERSON_FIELDS,
+          pageSize: params.pageSize || 100,
+          pageToken: params.pageToken,
+          sortOrder: params.sortOrder,
+          syncToken: params.syncToken,
+          requestSyncToken: params.requestSyncToken
+        },
+        headers: this.headers()
+      });
+      return response.data;
+    } catch (error) {
+      throw googlePeopleApiError(error, "list contacts");
+    }
+  }
+  async searchContacts(query, personFields, pageSize) {
+    try {
+      let response = await this.api.get("people:searchContacts", {
+        params: {
+          query,
+          readMask: personFields || DEFAULT_PERSON_FIELDS,
+          pageSize: pageSize || 30
+        },
+        headers: this.headers()
+      });
+      return response.data;
+    } catch (error) {
+      throw googlePeopleApiError(error, "search contacts");
+    }
+  }
+};
+var createGooglePeopleClient = (ctx) => new GooglePeopleClient({ token: ctx.auth.token });
+var listContactsRecipe = defineToolRecipe({
+  name: "List Contacts",
+  key: "list_contacts",
+  description: `Lists the authenticated user's contacts with pagination support. Returns contacts sorted by the specified order. Use the \`pageToken\` from a previous response to fetch the next page.`,
+  tags: {
+    destructive: false,
+    readOnly: true
+  },
+  defaultScopes: googlePeopleReadonlyScopes,
+  inputSchema: listContactsInputSchema,
+  outputSchema: listContactsOutputSchema,
+  handleInvocation: async ({
+    ctx,
+    dependencies
+  }) => {
+    let client = dependencies.createClient(ctx);
+    let result = await client.listContacts({
+      pageSize: ctx.input.pageSize,
+      pageToken: ctx.input.pageToken,
+      sortOrder: ctx.input.sortOrder
+    });
+    let contacts = (result.connections || []).map(formatContact);
+    return {
+      output: {
+        contacts,
+        nextPageToken: result.nextPageToken,
+        totalPeople: result.totalPeople,
+        totalItems: result.totalItems
+      },
+      message: `Listed **${contacts.length}** contacts${result.totalPeople ? ` out of ${result.totalPeople} total` : ""}.${result.nextPageToken ? " More pages available." : ""}`
+    };
+  }
+});
+var searchContactsRecipe = defineToolRecipe({
+  name: "Search Contacts",
+  key: "search_contacts",
+  description: `Searches the authenticated user's contacts by name, email address, phone number, or other fields. Returns matching contacts ranked by relevance.`,
+  tags: {
+    destructive: false,
+    readOnly: true
+  },
+  defaultScopes: googlePeopleReadonlyScopes,
+  inputSchema: searchContactsInputSchema,
+  outputSchema: searchContactsOutputSchema,
+  handleInvocation: async ({
+    ctx,
+    dependencies
+  }) => {
+    let client = dependencies.createClient(ctx);
+    let result = await client.searchContacts(ctx.input.query, void 0, ctx.input.pageSize);
+    let contacts = (result.results || []).map((item) => formatContact(item.person));
+    return {
+      output: { contacts },
+      message: `Found **${contacts.length}** contacts matching "${ctx.input.query}".`
+    };
+  }
+});
+var getContactRecipe = defineToolRecipe({
+  name: "Get Contact",
+  key: "get_contact",
+  description: `Retrieves detailed information about a specific contact by their resource name. Use \`people/me\` to get the authenticated user's profile. Returns all available contact fields.`,
+  tags: {
+    destructive: false,
+    readOnly: true
+  },
+  defaultScopes: googlePeopleReadonlyScopes,
+  inputSchema: getContactInputSchema,
+  outputSchema: contactOutputSchema,
+  handleInvocation: async ({
+    ctx,
+    dependencies
+  }) => {
+    let client = dependencies.createClient(ctx);
+    let result = await client.getContact(ctx.input.resourceName);
+    let contact = formatContact(result);
+    let displayName = contact.names?.[0]?.displayName || contact.emailAddresses?.[0]?.value || ctx.input.resourceName;
+    return {
+      output: contact,
+      message: `Retrieved contact **${displayName}**.`
+    };
+  }
+});
+export {
+  DEFAULT_PERSON_FIELDS,
+  GOOGLE_PEOPLE_API_BASE_URL,
+  GooglePeopleClient,
+  READONLY_PERSON_FIELDS,
+  addressSchema,
+  biographySchema,
+  birthdaySchema,
+  contactInputSchema,
+  contactOutputSchema,
+  createGooglePeopleClient,
+  customFieldSchema,
+  dateFieldSchema,
+  emailSchema,
+  eventSchema,
+  formatContact,
+  getContactInputSchema,
+  getContactRecipe,
+  googlePeopleApiError,
+  googlePeopleReadonlyScopes,
+  googlePeopleScopes,
+  googlePeopleServiceError,
+  listContactsInputSchema,
+  listContactsOutputSchema,
+  listContactsRecipe,
+  membershipSchema,
+  nameSchema,
+  nicknameSchema,
+  occupationSchema,
+  organizationSchema,
+  phoneSchema,
+  relationSchema,
+  searchContactsInputSchema,
+  searchContactsOutputSchema,
+  searchContactsRecipe,
+  urlSchema
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@slates/google-people-recipes",
+  "version": "1.0.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Ivan Siianytsia",
+  "license": "FSL 1.1",
+  "type": "module",
+  "source": "src/index.ts",
+  "files": [
+    "src/**",
+    "dist/**",
+    "README.md",
+    "package.json"
+  ],
+  "exports": {
+    "bun": "./src/index.ts",
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.module.js",
+    "default": "./dist/index.module.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.module.js",
+  "types": "dist/index.d.ts",
+  "unpkg": "./dist/index.module.js",
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts --passWithNoTests",
+    "lint": "prettier src/**/*.ts --check",
+    "build": "tsup --config ../../tsup.packages.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
+    "@slates/tool-recipes": "1.0.0-rc.1",
+    "slates": "1.0.0-rc.10",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "@slates/tsconfig": "1.0.0-rc.1",
+    "typescript": "5.8.2",
+    "vitest": "^3.1.2"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,78 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  formatContact,
+  getContactRecipe,
+  googlePeopleApiError,
+  listContactsRecipe,
+  searchContactsRecipe
+} from './index';
+
+describe('google people recipes', () => {
+  it('uses MCP-compatible top-level object input schemas', () => {
+    for (let recipe of [listContactsRecipe, searchContactsRecipe, getContactRecipe]) {
+      let jsonSchema = z.toJSONSchema(recipe.inputSchema) as Record<string, unknown>;
+
+      expect(jsonSchema.type).toBe('object');
+      expect(jsonSchema).not.toHaveProperty('oneOf');
+      expect(jsonSchema).not.toHaveProperty('anyOf');
+      expect(jsonSchema).not.toHaveProperty('allOf');
+    }
+  });
+
+  it('formats People API contact fields for tool output', () => {
+    let formatted = formatContact({
+      resourceName: 'people/c123',
+      etag: 'etag-123',
+      names: [{ displayName: 'Ada Lovelace', givenName: 'Ada', familyName: 'Lovelace' }],
+      emailAddresses: [{ value: 'ada@example.com', type: 'work' }],
+      phoneNumbers: [{ value: '+15551234567', type: 'mobile' }],
+      organizations: [{ name: 'Analytical Engines', title: 'Programmer' }],
+      birthdays: [{ date: { month: 12, day: 10 } }],
+      userDefined: [{ key: 'crmId', value: 'crm-123' }],
+      memberships: [
+        {
+          contactGroupMembership: {
+            contactGroupResourceName: 'contactGroups/friends'
+          }
+        }
+      ]
+    });
+
+    expect(formatted).toMatchObject({
+      resourceName: 'people/c123',
+      etag: 'etag-123',
+      names: [{ displayName: 'Ada Lovelace', givenName: 'Ada', familyName: 'Lovelace' }],
+      emailAddresses: [{ value: 'ada@example.com', type: 'work' }],
+      phoneNumbers: [{ value: '+15551234567', type: 'mobile' }],
+      organizations: [{ name: 'Analytical Engines', title: 'Programmer' }],
+      birthdays: [{ date: { month: 12, day: 10 } }],
+      userDefined: [{ key: 'crmId', value: 'crm-123' }],
+      memberships: [{ contactGroupResourceName: 'contactGroups/friends' }]
+    });
+  });
+
+  it('converts upstream API failures to ServiceError', () => {
+    let error = googlePeopleApiError(
+      {
+        response: {
+          status: 403,
+          statusText: 'Forbidden',
+          data: {
+            error: {
+              message: 'Request had insufficient authentication scopes.'
+            }
+          }
+        }
+      },
+      'list contacts'
+    );
+
+    expect(error).toBeInstanceOf(ServiceError);
+    expect(error.data.reason).toBe('google_people_api_error');
+    expect(error.data.upstreamStatus).toBe(403);
+    expect(error.data.message).toContain('Google People API list contacts failed');
+    expect(error.data.message).toContain('insufficient authentication scopes');
+  });
+});