@sonde/packs 0.1.1 → 0.1.3

package/src/integrations/meraki.ts

@@ -0,0 +1,344 @@
+import type {
+  FetchFn,
+  IntegrationConfig,
+  IntegrationCredentials,
+  IntegrationPack,
+  IntegrationProbeHandler,
+} from '@sonde/shared';
+
+// --- Auth helpers ---
+
+function buildAuthHeaders(credentials: IntegrationCredentials): Record<string, string> {
+  const apiKey = credentials.credentials.apiKey ?? '';
+  return { Authorization: `Bearer ${apiKey}` };
+}
+
+// --- REST helper ---
+
+async function merakiGet<T>(
+  path: string,
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+  params?: Record<string, string>,
+): Promise<T> {
+  const base = `${config.endpoint.replace(/\/$/, '')}/api/v1${path}`;
+  const url = new URL(base);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    ...buildAuthHeaders(credentials),
+    ...config.headers,
+  };
+
+  const res = await fetchFn(url.toString(), { headers });
+  if (!res.ok) {
+    throw new Error(`Meraki API returned ${res.status}: ${res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+// --- Probe handlers ---
+
+const organizationsList: IntegrationProbeHandler = async (
+  _params,
+  config,
+  credentials,
+  fetchFn,
+) => {
+  const orgs = await merakiGet<
+    Array<{
+      id?: string;
+      name?: string;
+      url?: string;
+    }>
+  >('/organizations', config, credentials, fetchFn);
+
+  return {
+    organizations: orgs.map((o) => ({
+      id: o.id ?? null,
+      name: o.name ?? null,
+      url: o.url ?? null,
+    })),
+    count: orgs.length,
+  };
+};
+
+const devicesStatuses: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const orgId = (params?.orgId as string) || credentials.credentials.orgId;
+  if (!orgId) throw new Error('orgId parameter is required');
+
+  const devices = await merakiGet<
+    Array<{
+      name?: string;
+      serial?: string;
+      model?: string;
+      status?: string;
+      lanIp?: string;
+      mac?: string;
+      networkId?: string;
+    }>
+  >(`/organizations/${encodeURIComponent(orgId)}/devices/statuses`, config, credentials, fetchFn);
+
+  return {
+    devices: devices.map((d) => ({
+      name: d.name ?? null,
+      serial: d.serial ?? null,
+      model: d.model ?? null,
+      status: d.status ?? null,
+      lanIp: d.lanIp ?? null,
+      mac: d.mac ?? null,
+      networkId: d.networkId ?? null,
+    })),
+    count: devices.length,
+  };
+};
+
+const switchPortStatuses: IntegrationProbeHandler = async (
+  params,
+  config,
+  credentials,
+  fetchFn,
+) => {
+  const serial = params?.serial as string;
+  if (!serial) throw new Error('serial parameter is required');
+
+  const ports = await merakiGet<
+    Array<{
+      portId?: string;
+      enabled?: boolean;
+      status?: string;
+      speed?: string;
+      duplex?: string;
+      cdp?: Record<string, unknown>;
+      lldp?: Record<string, unknown>;
+      errors?: string[];
+      usageInKb?: { sent?: number; recv?: number };
+    }>
+  >(`/devices/${encodeURIComponent(serial)}/switch/ports/statuses`, config, credentials, fetchFn);
+
+  return {
+    ports: ports.map((p) => ({
+      portId: p.portId ?? null,
+      enabled: p.enabled ?? false,
+      status: p.status ?? null,
+      speed: p.speed ?? null,
+      duplex: p.duplex ?? null,
+      cdp: p.cdp ?? null,
+      lldp: p.lldp ?? null,
+      errors: p.errors ?? [],
+      usage: p.usageInKb ?? null,
+    })),
+    count: ports.length,
+  };
+};
+
+const deviceLldpCdp: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const serial = params?.serial as string;
+  if (!serial) throw new Error('serial parameter is required');
+
+  const data = await merakiGet<{
+    ports?: Record<
+      string,
+      {
+        cdp?: { deviceId?: string; platform?: string; portId?: string; address?: string };
+        lldp?: { systemName?: string; portId?: string; managementAddress?: string };
+      }
+    >;
+  }>(`/devices/${encodeURIComponent(serial)}/lldpCdp`, config, credentials, fetchFn);
+
+  const ports = data.ports ?? {};
+  const neighbors = Object.entries(ports).map(([portId, info]) => ({
+    portId,
+    cdp: info.cdp ?? null,
+    lldp: info.lldp ?? null,
+  }));
+
+  return { neighbors, count: neighbors.length };
+};
+
+const deviceClients: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const serial = params?.serial as string;
+  if (!serial) throw new Error('serial parameter is required');
+
+  const queryParams: Record<string, string> = {};
+  const timespan = params?.timespan as number | undefined;
+  if (timespan) queryParams.timespan = String(timespan);
+
+  const clients = await merakiGet<
+    Array<{
+      mac?: string;
+      ip?: string;
+      description?: string;
+      vlan?: number;
+      switchport?: string;
+      usage?: { sent?: number; recv?: number };
+    }>
+  >(
+    `/devices/${encodeURIComponent(serial)}/clients`,
+    config,
+    credentials,
+    fetchFn,
+    queryParams,
+  );
+
+  return {
+    clients: clients.map((c) => ({
+      mac: c.mac ?? null,
+      ip: c.ip ?? null,
+      description: c.description ?? null,
+      vlan: c.vlan ?? null,
+      switchport: c.switchport ?? null,
+      usage: c.usage ?? null,
+    })),
+    count: clients.length,
+  };
+};
+
+const networksList: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const orgId = (params?.orgId as string) || credentials.credentials.orgId;
+  if (!orgId) throw new Error('orgId parameter is required');
+
+  const networks = await merakiGet<
+    Array<{
+      id?: string;
+      name?: string;
+      productTypes?: string[];
+      timeZone?: string;
+      tags?: string[];
+    }>
+  >(`/organizations/${encodeURIComponent(orgId)}/networks`, config, credentials, fetchFn);
+
+  return {
+    networks: networks.map((n) => ({
+      id: n.id ?? null,
+      name: n.name ?? null,
+      productTypes: n.productTypes ?? [],
+      timeZone: n.timeZone ?? null,
+      tags: n.tags ?? [],
+    })),
+    count: networks.length,
+  };
+};
+
+// --- Pack definition ---
+
+export const merakiPack: IntegrationPack = {
+  manifest: {
+    name: 'meraki',
+    type: 'integration',
+    version: '0.1.0',
+    description: 'Cisco Meraki — device fleet status, switch ports, and network topology',
+    requires: { groups: [], files: [], commands: [] },
+    probes: [
+      {
+        name: 'organizations.list',
+        description: 'List organizations accessible by the API key',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'devices.statuses',
+        description: 'List device statuses across an organization',
+        capability: 'observe',
+        params: {
+          orgId: {
+            type: 'string',
+            description: 'Meraki organization ID (falls back to credential orgId)',
+            required: false,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'switch.port-statuses',
+        description: 'Get port statuses for a switch including speed, duplex, and neighbors',
+        capability: 'observe',
+        params: {
+          serial: {
+            type: 'string',
+            description: 'Device serial number',
+            required: true,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'device.lldp-cdp',
+        description: 'Get LLDP and CDP neighbor information for a device',
+        capability: 'observe',
+        params: {
+          serial: {
+            type: 'string',
+            description: 'Device serial number',
+            required: true,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'device.clients',
+        description: 'List clients connected to a device',
+        capability: 'observe',
+        params: {
+          serial: {
+            type: 'string',
+            description: 'Device serial number',
+            required: true,
+          },
+          timespan: {
+            type: 'number',
+            description: 'Lookback period in seconds (default: 86400)',
+            required: false,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'networks.list',
+        description: 'List networks in an organization',
+        capability: 'observe',
+        params: {
+          orgId: {
+            type: 'string',
+            description: 'Meraki organization ID (falls back to credential orgId)',
+            required: false,
+          },
+        },
+        timeout: 15000,
+      },
+    ],
+    runbook: {
+      category: 'network',
+      probes: ['organizations.list', 'devices.statuses'],
+      parallel: true,
+    },
+  },
+
+  handlers: {
+    'organizations.list': organizationsList,
+    'devices.statuses': devicesStatuses,
+    'switch.port-statuses': switchPortStatuses,
+    'device.lldp-cdp': deviceLldpCdp,
+    'device.clients': deviceClients,
+    'networks.list': networksList,
+  },
+
+  testConnection: async (config, credentials, fetchFn) => {
+    const url = `${config.endpoint.replace(/\/$/, '')}/api/v1/organizations`;
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...buildAuthHeaders(credentials),
+      ...config.headers,
+    };
+
+    const res = await fetchFn(url, { headers });
+    return res.ok;
+  },
+};

package/src/integrations/nutanix.test.ts

@@ -924,10 +924,10 @@ describe('nutanix pack', () => {
       expect(result).toBe(false);
     });
 
-    it('returns false on network error', async () => {
+    it('throws on network error', async () => {
       const fetchFn = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
-      const result = await nutanixPack.testConnection(ntnxConfig, basicCreds, fetchFn);
-      expect(result).toBe(false);
+      await expect(nutanixPack.testConnection(ntnxConfig, basicCreds, fetchFn))
+        .rejects.toThrow('ECONNREFUSED');
     });
 
     it('returns false when data is null', async () => {

package/src/integrations/nutanix.ts

@@ -1438,23 +1438,19 @@ export const nutanixPack: IntegrationPack = {
   },
 
   testConnection: async (config, credentials, fetchFn) => {
-    try {
-      const url = nutanixUrl(config.endpoint, 'clustermgmt', 'config/clusters');
-      const fullUrl = new URL(url);
-      fullUrl.searchParams.set('$limit', '1');
-
-      const headers: Record<string, string> = {
-        Accept: 'application/json',
-        ...buildAuthHeaders(credentials),
-        ...config.headers,
-      };
+    const url = nutanixUrl(config.endpoint, 'clustermgmt', 'config/clusters');
+    const fullUrl = new URL(url);
+    fullUrl.searchParams.set('$limit', '1');
+
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...buildAuthHeaders(credentials),
+      ...config.headers,
+    };
 
-      const res = await fetchFn(fullUrl.toString(), { headers });
-      if (!res.ok) return false;
-      const body = (await res.json()) as { data?: unknown };
-      return body.data != null;
-    } catch {
-      return false;
-    }
+    const res = await fetchFn(fullUrl.toString(), { headers });
+    if (!res.ok) return false;
+    const body = (await res.json()) as { data?: unknown };
+    return body.data != null;
   },
 };

package/src/integrations/pagerduty.ts

@@ -0,0 +1,319 @@
+import type {
+  FetchFn,
+  IntegrationConfig,
+  IntegrationCredentials,
+  IntegrationPack,
+  IntegrationProbeHandler,
+} from '@sonde/shared';
+
+// --- Auth helpers ---
+
+/** Build PagerDuty auth header: Token token=<key> */
+function buildAuthHeaders(credentials: IntegrationCredentials): Record<string, string> {
+  const token = credentials.credentials.token ?? '';
+  return { Authorization: `Token token=${token}` };
+}
+
+// --- REST helper ---
+
+async function pagerdutyGet<T>(
+  path: string,
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+  params?: Record<string, string>,
+): Promise<T> {
+  const base = `${config.endpoint.replace(/\/$/, '')}${path}`;
+  const url = new URL(base);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    ...buildAuthHeaders(credentials),
+    ...config.headers,
+  };
+
+  const res = await fetchFn(url.toString(), { headers });
+  if (!res.ok) {
+    throw new Error(`PagerDuty API returned ${res.status}: ${res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+// --- Probe handlers ---
+
+const incidentsList: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const queryParams: Record<string, string> = {};
+  const status = params?.status as string | undefined;
+  if (status) queryParams['statuses[]'] = status;
+  const since = params?.since as string | undefined;
+  if (since) queryParams.since = since;
+  const until = params?.until as string | undefined;
+  if (until) queryParams.until = until;
+
+  const data = await pagerdutyGet<{
+    incidents?: Array<{
+      id: string;
+      incident_number?: number;
+      title?: string;
+      status?: string;
+      urgency?: string;
+      created_at?: string;
+      service?: { id?: string; summary?: string };
+      assignees?: Array<{ summary?: string }>;
+    }>;
+    total?: number;
+  }>('/incidents', config, credentials, fetchFn, queryParams);
+
+  const incidents = data.incidents ?? [];
+  return {
+    incidents: incidents.map((i) => ({
+      id: i.id,
+      incidentNumber: i.incident_number ?? null,
+      title: i.title ?? null,
+      status: i.status ?? null,
+      urgency: i.urgency ?? null,
+      createdAt: i.created_at ?? null,
+      service: i.service?.summary ?? null,
+      assignees: (i.assignees ?? []).map((a) => a.summary ?? ''),
+    })),
+    total: data.total ?? incidents.length,
+    count: incidents.length,
+  };
+};
+
+const incidentsTriggered: IntegrationProbeHandler = async (
+  _params,
+  config,
+  credentials,
+  fetchFn,
+) => {
+  const data = await pagerdutyGet<{
+    incidents?: Array<{
+      id: string;
+      incident_number?: number;
+      title?: string;
+      status?: string;
+      urgency?: string;
+      created_at?: string;
+      service?: { id?: string; summary?: string };
+      assignees?: Array<{ summary?: string }>;
+    }>;
+    total?: number;
+  }>('/incidents', config, credentials, fetchFn, {
+    'statuses[]': 'triggered,acknowledged',
+  });
+
+  const incidents = data.incidents ?? [];
+  return {
+    incidents: incidents.map((i) => ({
+      id: i.id,
+      incidentNumber: i.incident_number ?? null,
+      title: i.title ?? null,
+      status: i.status ?? null,
+      urgency: i.urgency ?? null,
+      createdAt: i.created_at ?? null,
+      service: i.service?.summary ?? null,
+      assignees: (i.assignees ?? []).map((a) => a.summary ?? ''),
+    })),
+    total: data.total ?? incidents.length,
+    count: incidents.length,
+  };
+};
+
+const servicesList: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  const data = await pagerdutyGet<{
+    services?: Array<{
+      id: string;
+      name?: string;
+      status?: string;
+      description?: string;
+      created_at?: string;
+    }>;
+    total?: number;
+  }>('/services', config, credentials, fetchFn);
+
+  const services = data.services ?? [];
+  return {
+    services: services.map((s) => ({
+      id: s.id,
+      name: s.name ?? null,
+      status: s.status ?? null,
+      description: s.description ?? null,
+      createdAt: s.created_at ?? null,
+    })),
+    count: services.length,
+  };
+};
+
+const serviceDetail: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const id = params?.id as string;
+  if (!id) throw new Error('id parameter is required (service ID)');
+
+  const data = await pagerdutyGet<{
+    service?: {
+      id: string;
+      name?: string;
+      status?: string;
+      description?: string;
+      escalation_policy?: { id?: string; summary?: string };
+      integrations?: Array<{ id?: string; summary?: string; type?: string }>;
+    };
+  }>(`/services/${id}`, config, credentials, fetchFn);
+
+  const svc = data.service;
+  if (!svc) throw new Error(`Service ${id} not found`);
+
+  return {
+    id: svc.id,
+    name: svc.name ?? null,
+    status: svc.status ?? null,
+    description: svc.description ?? null,
+    escalationPolicy: svc.escalation_policy?.summary ?? null,
+    integrations: (svc.integrations ?? []).map((i) => ({
+      id: i.id ?? null,
+      summary: i.summary ?? null,
+      type: i.type ?? null,
+    })),
+  };
+};
+
+const oncallList: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const queryParams: Record<string, string> = {};
+  const scheduleIds = params?.schedule_ids as string | undefined;
+  if (scheduleIds) queryParams['schedule_ids[]'] = scheduleIds;
+
+  const data = await pagerdutyGet<{
+    oncalls?: Array<{
+      user?: { id?: string; summary?: string };
+      schedule?: { id?: string; summary?: string };
+      escalation_policy?: { id?: string; summary?: string };
+      escalation_level?: number;
+      start?: string;
+      end?: string;
+    }>;
+  }>('/oncalls', config, credentials, fetchFn, queryParams);
+
+  const oncalls = data.oncalls ?? [];
+  return {
+    oncalls: oncalls.map((o) => ({
+      user: o.user?.summary ?? null,
+      schedule: o.schedule?.summary ?? null,
+      escalationPolicy: o.escalation_policy?.summary ?? null,
+      escalationLevel: o.escalation_level ?? null,
+      start: o.start ?? null,
+      end: o.end ?? null,
+    })),
+    count: oncalls.length,
+  };
+};
+
+// --- Pack definition ---
+
+export const pagerdutyPack: IntegrationPack = {
+  manifest: {
+    name: 'pagerduty',
+    type: 'integration',
+    version: '0.1.0',
+    description:
+      'PagerDuty — incidents, services, on-call schedules',
+    requires: { groups: [], files: [], commands: [] },
+    probes: [
+      {
+        name: 'incidents.list',
+        description: 'List incidents with optional status, since, and until filters',
+        capability: 'observe',
+        params: {
+          status: {
+            type: 'string',
+            description:
+              'Filter by status (triggered, acknowledged, resolved)',
+            required: false,
+          },
+          since: {
+            type: 'string',
+            description: 'Start date (ISO 8601)',
+            required: false,
+          },
+          until: {
+            type: 'string',
+            description: 'End date (ISO 8601)',
+            required: false,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'incidents.triggered',
+        description: 'List active incidents (triggered + acknowledged)',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'services.list',
+        description: 'List services with status',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'service.detail',
+        description: 'Service detail with integrations and escalation policy',
+        capability: 'observe',
+        params: {
+          id: {
+            type: 'string',
+            description: 'Service ID',
+            required: true,
+          },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'oncall.list',
+        description: 'Current on-call schedules',
+        capability: 'observe',
+        params: {
+          schedule_ids: {
+            type: 'string',
+            description: 'Comma-separated schedule IDs to filter',
+            required: false,
+          },
+        },
+        timeout: 15000,
+      },
+    ],
+    runbook: {
+      category: 'itsm',
+      probes: ['incidents.triggered', 'services.list'],
+      parallel: true,
+    },
+  },
+
+  handlers: {
+    'incidents.list': incidentsList,
+    'incidents.triggered': incidentsTriggered,
+    'services.list': servicesList,
+    'service.detail': serviceDetail,
+    'oncall.list': oncallList,
+  },
+
+  testConnection: async (config, credentials, fetchFn) => {
+    const url = `${config.endpoint.replace(/\/$/, '')}/abilities`;
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...buildAuthHeaders(credentials),
+      ...config.headers,
+    };
+
+    const res = await fetchFn(url, { headers });
+    return res.ok;
+  },
+};