scrapeloop-mcp 0.7.0 → 0.8.0

package/src/mutation-policies.js

@@ -0,0 +1,232 @@
+/**
+ * Retry contracts for every MCP operation that does not use HTTP GET.
+ *
+ * A POST may still be read-only, such as an estimate with a JSON filter body.
+ * Every true mutation declares whether it is provably idempotent, protected by
+ * a durable caller key, reconciliation-only, or forbidden from automatic retry.
+ */
+
+const read = (method = 'POST') => ({ method, effect: 'read', retry: 'bounded' });
+const idempotent = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'idempotent',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const keyed = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'idempotency_key',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const reconcile = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'reconcile',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const never = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'never',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+
+export const MUTATION_POLICIES = Object.freeze({
+  create_integration: keyed('POST', ['list_integrations'], ['vendor', 'plugin_kind']),
+  add_credential: reconcile('POST', ['list_credentials'], ['integration_id', 'label']),
+  test_credential: idempotent('POST', ['list_credentials'], ['credential_id']),
+  preview_pipeline: read(),
+  preview_scrape_plan: read(),
+  create_scrape_plan: keyed('POST', ['list_scrape_plans'], ['name', 'target_list_id', 'kind']),
+  pause_scrape_plan: never('POST', ['get_scrape_plan'], ['plan_id']),
+  estimate_scrape: read(),
+  submit_scrape: keyed('POST', ['list_jobs'], ['kind', 'integration_id', 'credential_id', 'table_id']),
+  cancel_job: never('POST', ['get_job'], ['job_id', 'status']),
+  attach_job_to_table: idempotent('POST', ['get_job'], ['job_id']),
+  search_leads: read(),
+  estimate_leads: read(),
+  expand_job_titles: read(),
+  reveal_lead: idempotent('POST', ['search_leads', 'get_credits'], ['global_person_id']),
+  save_leads: reconcile('POST', ['search_leads', 'get_credits'], ['global_person_ids']),
+  estimate_lead_import: read(),
+  import_leads_to_table: reconcile('POST', ['get_lists', 'get_list_rows'], ['list_id', 'new_list_name']),
+  save_search: idempotent('POST', ['list_saved_searches'], ['name']),
+  bulk_verify_leads: reconcile('POST', ['list_jobs'], ['lead_ids', 'global_person_ids']),
+  search_local_leads: read(),
+  estimate_local_leads: read(),
+  reveal_local_lead: idempotent('POST', ['search_local_leads', 'get_credits'], ['place_id']),
+  fill_coverage_gap: reconcile('POST', ['list_jobs', 'search_local_leads'], ['filters']),
+  verify_email: never('POST', ['get_credits'], ['email']),
+  verify_catchall: keyed('POST', ['get_credits'], ['email']),
+  preview_cleaners: read(),
+  apply_cleaners: reconcile('POST', ['get_lists'], ['list_id', 'cleaners']),
+  create_preset: reconcile('POST', ['list_presets'], ['name']),
+  estimate_enrich: read(),
+  run_enrich: never('POST', ['list_jobs'], ['preset_slug', 'preset_id', 'lead_ids', 'list_id']),
+  test_recipe: never('POST', ['get_credits'], ['lead_id']),
+  update_ai_settings: idempotent('PUT', ['get_ai_settings'], ['default_ai_model', 'enabled_models']),
+  update_playbook: idempotent('PUT', ['get_playbook'], ['channels', 'scrape', 'tables', 'checks', 'routing', 'campaigns']),
+  set_playbook_niches: idempotent('PUT', ['get_playbook'], ['niches']),
+  update_ai_context: idempotent('PUT', ['get_ai_context'], ['company_description', 'icp']),
+  generate_ai_context: never('POST', ['get_ai_context', 'get_credits'], ['domain']),
+  create_strategy: reconcile('POST', ['list_strategies'], ['name']),
+  assign_strategy: reconcile('POST', ['list_strategies'], ['strategy_id', 'lead_ids', 'list_id']),
+  import_instantly_campaigns: reconcile('POST', ['list_campaigns'], ['credential_id', 'campaign_ids']),
+  import_instantly_lead_list: reconcile('POST', ['get_lists'], ['credential_id', 'lead_list_id']),
+  create_segment: reconcile('POST', ['list_segments'], ['name']),
+  preview_segment: read(),
+  preview_add_leads_to_campaign: read(),
+  add_leads_to_campaign: never('POST', ['list_campaigns', 'campaign_stats'], ['campaign_id', 'list_id']),
+  create_campaign: keyed('POST', ['list_campaigns'], ['name', 'sender_credential_id', 'source_list_id']),
+  update_campaign: idempotent('PATCH', ['list_campaigns'], ['campaign_id']),
+  duplicate_campaign: keyed('POST', ['list_campaigns'], ['campaign_id']),
+  activate_campaign: keyed('POST', ['list_campaigns', 'campaign_stats'], ['campaign_id', 'status']),
+  pause_campaign: reconcile('POST', ['list_campaigns'], ['campaign_id', 'status']),
+  sync_campaign: idempotent('POST', ['campaign_stats'], ['campaign_id']),
+  update_sender_config: idempotent('PUT', ['get_sender_config'], ['credential_id']),
+  // A full-document PUT: sending it twice leaves the campaign in the same state
+  // as sending it once, so a lost response is safe to retry.
+  create_sender_fields: idempotent(
+    'POST', ['get_campaign_field_mapping'], ['campaign_id', 'names'],
+  ),
+  set_campaign_field_mapping: idempotent(
+    'PUT',
+    ['get_campaign_field_mapping'],
+    ['campaign_id'],
+  ),
+  create_list: keyed('POST', ['get_lists'], ['name']),
+  add_list_members: idempotent('POST', ['get_list_rows'], ['list_id', 'global_person_ids']),
+  create_pipeline: idempotent('POST', ['get_pipeline'], ['operation_id']),
+  create_workbook: reconcile('POST', ['list_workbooks'], ['name', 'list_ids']),
+  add_table_to_workbook: reconcile(
+    'POST',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id', 'new_table_name'],
+  ),
+  remove_table_from_workbook: reconcile(
+    'DELETE',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id'],
+  ),
+  reorder_workbook_table: idempotent(
+    'PATCH',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id', 'position'],
+  ),
+  duplicate_workbook: reconcile(
+    'POST',
+    ['list_workbooks'],
+    ['workbook_id', 'name', 'folder_id'],
+  ),
+  create_folder: reconcile('POST', ['list_workbooks'], ['name']),
+  move_to_folder: idempotent(
+    'PATCH',
+    ['list_workbooks'],
+    ['folder_id', 'workbook_id', 'list_id'],
+  ),
+  delete_folder: never('DELETE', ['list_workbooks'], ['folder_id']),
+  create_table: idempotent('POST', ['get_tables'], ['name', 'operation_id']),
+  create_table_column: idempotent(
+    'POST',
+    ['get_table_columns'],
+    ['table_id', 'label', 'operation_id'],
+  ),
+  create_table_preset_column: idempotent(
+    'POST',
+    ['get_table_columns'],
+    ['table_id', 'preset_slug', 'preset_id', 'label', 'operation_id'],
+  ),
+  // High-value create: with auto_run it starts a credit-billed backfill, and API
+  // idempotency is per (list_id, client_operation_id), so a fresh key on retry
+  // would make a second column AND a second paid backfill. One durable key.
+  create_table_native_column: keyed(
+    'POST',
+    ['get_table_columns', 'get_table_native_tools'],
+    ['table_id', 'tool', 'label', 'operation_id'],
+  ),
+  set_table_cells: idempotent('POST', ['list_table_rows'], ['table_id']),
+  import_leads: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dedupe_by', 'operation_id'],
+  ),
+  import_leads_csv: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dedupe_by', 'operation_id'],
+  ),
+  preview_import: read(),
+  preview_apify_import: read(),
+  import_apify_dataset: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dataset_id', 'preview_hash'],
+  ),
+  capture_community_intent: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['source_url', 'public_profile_url', 'observed_at', 'operation_id'],
+  ),
+  save_flow_layout: idempotent('PUT', ['get_flow_graph'], ['scope_key']),
+  create_table_flow_rule: reconcile('POST', ['list_table_flow_rules'], ['list_id', 'name']),
+  toggle_table_flow_rule: idempotent('PATCH', ['list_table_flow_rules'], ['list_id', 'rule_id', 'enabled']),
+  create_campaign_flow_rule: reconcile(
+    'POST',
+    ['list_campaign_flow_rules'],
+    ['campaign_id', 'name'],
+  ),
+  toggle_campaign_flow_rule: idempotent(
+    'PATCH',
+    ['list_campaign_flow_rules'],
+    ['campaign_id', 'rule_id', 'enabled'],
+  ),
+  test_flow_rule: never(
+    'POST',
+    ['get_flow_rule_stats', 'list_table_flow_rules', 'list_campaign_flow_rules'],
+    ['list_id', 'campaign_id', 'rule_id', 'lead_id', 'execute'],
+  ),
+  preview_send_to_table: read(),
+  send_to_table: idempotent('POST', ['get_list_rows'], ['list_id', 'destination_list_id', 'new_table_name']),
+  preview_table_write_back: read(),
+  apply_table_write_back: idempotent('POST', ['get_list_rows'], ['list_id', 'column_id', 'field']),
+  export_table_csv: reconcile('POST', ['get_table_export'], ['list_id', 'filename']),
+  create_table_view: idempotent(
+    'POST',
+    ['list_table_views'],
+    ['list_id', 'name', 'operation_id'],
+  ),
+  update_table_view: idempotent('PATCH', ['list_table_views'], ['list_id', 'view_id']),
+  delete_table_view: reconcile('DELETE', ['list_table_views'], ['list_id', 'view_id']),
+  estimate_table_column: read(),
+  run_table_column: never('POST', ['get_list_history'], ['list_id', 'column_id']),
+  run_scope_summary: read(),
+  estimate_table_run_all: read(),
+  run_table_all: never('POST', ['get_list_history'], ['list_id', 'column_ids']),
+  remove_table_rows: reconcile('DELETE', ['list_table_rows'], ['list_id', 'lead_ids']),
+  create_list_webhook: keyed('POST', ['get_list_webhook'], ['list_id']),
+  update_list_webhook: idempotent('PATCH', ['get_list_webhook'], ['list_id']),
+  revoke_list_webhook: never('DELETE', ['get_list_webhook'], ['list_id']),
+  export_list_to_webhook: never('POST', ['get_list_history'], ['list_id']),
+  delete_list: never('DELETE', ['get_lists'], ['list_id']),
+  delete_campaign: never('DELETE', ['list_campaigns'], ['campaign_id']),
+  update_reply: idempotent('PATCH', ['list_replies'], ['reply_id']),
+  add_suppression_entry: reconcile('POST', ['list_suppression_entries'], ['kind', 'value']),
+  remove_suppression_entry: reconcile('DELETE', ['list_suppression_entries'], ['entry_id']),
+  update_suppression_settings: idempotent('PUT', ['get_suppression_settings'], ['auto_suppress_mode']),
+  roadmap_update_status: idempotent('PATCH', ['roadmap_list'], ['slug', 'status']),
+  roadmap_create_item: reconcile('POST', ['roadmap_list'], ['slug']),
+  roadmap_update_plan: idempotent('PATCH', ['roadmap_list'], ['slug']),
+});
+
+export const RETRY_CONTRACT_COPY = Object.freeze({
+  bounded: 'Read-only operation. Retries transport errors, 429, and 5xx with bounded backoff.',
+  idempotent: 'Proven idempotent write. Retries transient failures with bounded backoff.',
+  idempotency_key: 'Durable Idempotency-Key required. Transient retries replay one stored result.',
+  reconcile: 'One request only. An ambiguous result returns reconciliation tools and stable match fields.',
+  never: 'Never retried automatically. An ambiguous result must be reconciled before any new attempt.',
+});