@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/settings.d.ts

@@ -0,0 +1,448 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.settings` (Settings): 18 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"activate_sso_org_sso_activate_post">;
+ *
+ * Reference with examples: settings.md
+ */
+/* eslint-disable */
+
+/** `g8.api.settings.<member>` -> the operationId it calls. */
+export interface SettingsMembers {
+  activateSso: "activate_sso_org_sso_activate_post";
+  configureOidcSso: "configure_oidc_sso_org_sso_oidc_put";
+  configureSamlSso: "configure_saml_sso_org_sso_saml_put";
+  deactivateSso: "deactivate_sso_org_sso_deactivate_post";
+  deleteSsoConfig: "delete_sso_config_org_sso_delete";
+  getCostSettings: "get_cost_settings_org_settings_cost_get";
+  getDeliverabilityProtection: "get_deliverability_protection_org_settings_deliverability_protection_get";
+  getDepartments: "get_departments_org_settings_departments_get";
+  getOutboundTracking: "get_outbound_tracking_org_settings_outbound_tracking_get";
+  getSsoConfig: "get_sso_config_org_sso_get";
+  getSsoMetadata: "get_sso_metadata_org_sso_metadata_get";
+  seedDepartmentDefaults: "seed_department_defaults_org_settings_departments_seed_defaults_post";
+  syncSsoConfig: "sync_sso_config_org_sso_sync_post";
+  updateCostSettings: "update_cost_settings_org_settings_cost_put";
+  updateDeliverabilityProtection: "update_deliverability_protection_org_settings_deliverability_protection_put";
+  updateDepartments: "update_departments_org_settings_departments_put";
+  updateOutboundTracking: "update_outbound_tracking_org_settings_outbound_tracking_put";
+  updateSsoEnforcement: "update_sso_enforcement_org_sso_enforcement_put";
+}
+
+/** Input and output of every `g8.api.settings` operation, keyed by operationId. */
+export interface SettingsOperations {
+  /**
+   * POST /org/sso/activate
+   * Activate Sso
+   * tier: write · scope: account:write
+   */
+  activate_sso_org_sso_activate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/sso/oidc
+   * Configure Oidc Sso
+   * tier: write · scope: account:write
+   */
+  configure_oidc_sso_org_sso_oidc_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OIDCConfigRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/sso/saml
+   * Configure Saml Sso
+   * tier: write · scope: account:write
+   */
+  configure_saml_sso_org_sso_saml_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SAMLConfigRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * POST /org/sso/deactivate
+   * Deactivate Sso
+   * tier: destructive · scope: account:delete
+   */
+  deactivate_sso_org_sso_deactivate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * DELETE /org/sso
+   * Delete Sso Config
+   * tier: destructive · scope: account:delete
+   */
+  delete_sso_config_org_sso_delete: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/settings/cost
+   * Get Cost Settings
+   * tier: read · scope: account:read
+   */
+  get_cost_settings_org_settings_cost_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/settings/deliverability-protection
+   * Get Deliverability Protection
+   * tier: read · scope: account:read
+   */
+  get_deliverability_protection_org_settings_deliverability_protection_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/settings/departments
+   * Get Departments
+   * tier: read · scope: account:read
+   */
+  get_departments_org_settings_departments_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/settings/outbound-tracking
+   * Get Outbound Tracking
+   * tier: read · scope: account:read
+   */
+  get_outbound_tracking_org_settings_outbound_tracking_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/sso
+   * Get Sso Config
+   * tier: read · scope: account:read
+   */
+  get_sso_config_org_sso_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * GET /org/sso/metadata
+   * Get Sso Metadata
+   * tier: read · scope: account:read
+   */
+  get_sso_metadata_org_sso_metadata_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * POST /org/settings/departments/seed-defaults
+   * Seed Department Defaults
+   * tier: destructive · scope: account:delete
+   */
+  seed_department_defaults_org_settings_departments_seed_defaults_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * POST /org/sso/sync
+   * Sync Sso Config
+   * tier: external · scope: integrations:run
+   */
+  sync_sso_config_org_sso_sync_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/settings/cost
+   * Update Cost Settings
+   * tier: write · scope: account:write
+   */
+  update_cost_settings_org_settings_cost_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgCostSettingsRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/settings/deliverability-protection
+   * Update Deliverability Protection
+   * tier: write · scope: account:write
+   */
+  update_deliverability_protection_org_settings_deliverability_protection_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgDeliverabilityProtectionRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/settings/departments
+   * Update Departments
+   * tier: write · scope: account:write
+   */
+  update_departments_org_settings_departments_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgDepartmentsUpdateRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/settings/outbound-tracking
+   * Update Outbound Tracking
+   * tier: write · scope: account:write
+   */
+  update_outbound_tracking_org_settings_outbound_tracking_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgOutboundTrackingRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+  /**
+   * PUT /org/sso/enforcement
+   * Update Sso Enforcement
+   * tier: destructive · scope: account:delete
+   */
+  update_sso_enforcement_org_sso_enforcement_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SsoEnforcementRequest;
+  };
+    output: ApiResponse_SettingsPayload_;
+  };
+}
+
+// 15 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_SettingsPayload_ {
+  data: SettingsPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Commission model. v1 supports ``none`` and ``per_meeting`` only —
+ * ``revenue_pct`` needs per-rep deal attribution we don't have cleanly yet
+ * (Phase 2), so it is rejected by the validator.
+ */
+export interface CommissionConfig {
+  mode?: "none" | "per_meeting";
+  per_employee_overrides?: Record<string, EmployeeCommissionOverride>;
+  per_meeting_rate?: number;
+}
+
+export interface DepartmentEntry {
+  color?: string | null;
+  description?: string | null;
+  hidden?: boolean;
+  id?: string;
+  is_system_seed?: boolean;
+  name: string;
+  slug: string;
+  sort_order?: number;
+}
+
+/** Optional per-rep commission rate override (else the org default applies). */
+export interface EmployeeCommissionOverride {
+  per_meeting_rate?: number;
+}
+
+/**
+ * A single rep's labor cost. ``role`` is informational (sdr/ae/other).
+ *
+ * ``name`` is intentionally optional (default "") at the API layer — direct
+ * API callers may store cost keyed by email alone. The settings UI requires a
+ * name for usability; a27/a28 fall back to the email for display when blank.
+ */
+export interface EmployeeCost {
+  monthly_cost?: number;
+  name?: string;
+  role?: "sdr" | "ae" | "other";
+}
+
+/**
+ * OIDC sign-in configuration.
+ *
+ * `client_secret` is write-only in effect: the app stores it and the read
+ * endpoint does not hand it back.
+ */
+export interface OIDCConfigRequest {
+  allowed_domains?: Array<string> | null;
+  authorize_url: string;
+  client_id: string;
+  /** Stored, never returned by the read endpoint. */
+  client_secret: string;
+  /** IdP name: okta, azure, google, custom. */
+  provider_name: string;
+  /** See the SAML note — set this later. */
+  require_sso?: boolean;
+  token_url: string;
+  userinfo_url: string;
+}
+
+/** Labour cost per rep and the commission model. REPLACES the stored config. */
+export interface OrgCostSettingsRequest {
+  commission?: CommissionConfig;
+  employees?: Record<string, EmployeeCost>;
+  enabled?: boolean;
+  version?: number;
+}
+
+/** Which high-risk content categories are blocked before a send. */
+export interface OrgDeliverabilityProtectionRequest {
+  categories?: Array<string>;
+  enabled?: boolean;
+  version?: 1;
+}
+
+/** The department taxonomy. REPLACES the whole list. */
+export interface OrgDepartmentsUpdateRequest {
+  entries: Array<DepartmentEntry>;
+}
+
+/** UTM tagging of outbound links, per channel. */
+export interface OrgOutboundTrackingRequest {
+  channels?: OutboundTrackingChannels;
+  enabled?: boolean;
+  utm_source_prefix?: string | null;
+  version?: number;
+}
+
+/**
+ * Per-channel UTM injection toggles. email, linkedin, and whatsapp are
+ * wired into their send paths; sms/voice/dialer use booking-link tokens.
+ */
+export interface OutboundTrackingChannels {
+  dialer?: boolean;
+  email?: boolean;
+  linkedin?: boolean;
+  sms?: boolean;
+  voice?: boolean;
+  whatsapp?: boolean;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * SAML sign-in configuration.
+ *
+ * The certificate and URLs come from the identity provider. Nothing here is
+ * guessable, which is why every one of the first four fields is required —
+ * a half-configured SSO that then gets activated is how an org locks itself
+ * out.
+ */
+export interface SAMLConfigRequest {
+  /** Email domains allowed to sign in this way. */
+  allowed_domains?: Array<string> | null;
+  /** X.509 certificate from the IdP, PEM format. */
+  idp_certificate: string;
+  /** Identity Provider Entity ID. */
+  idp_entity_id: string;
+  /** SSO URL from the IdP. */
+  idp_sso_url: string;
+  /** IdP name: okta, azure, google, onelogin, custom. */
+  provider_name: string;
+  /** Make SSO the ONLY way in. False here and set it later with `PUT /org/sso/enforcement` once you have signed in through SSO yourself — that ordering is what stops a lockout. */
+  require_sso?: boolean;
+}
+
+/**
+ * An open envelope for a settings object.
+ *
+ * Open because an ontology concept and an SSO config both grow fields as the
+ * product does, and on a settings read a dropped field reads as "not
+ * configured" rather than "we did not tell you".
+ */
+export type SettingsPayload = Record<string, unknown>;
+
+/**
+ * Whether SSO is the only way in, and on what terms.
+ *
+ * `require_sso: true` blocks every other sign-in method. Do it only once you
+ * have signed in through SSO yourself.
+ */
+export interface SsoEnforcementRequest {
+  /** Whether members on an unverified email domain may still sign in. */
+  allow_unverified_domain_members?: boolean | null;
+  allowed_domains?: Array<string> | null;
+  /** How long an SSO grant stays valid. */
+  grant_ttl_minutes?: number | null;
+  /** True makes SSO the only way in. Defaults to false, as the app's does. */
+  require_sso?: boolean;
+}