feat(crm): org-scoped CRM with a graph-and-loop research agent (#1272)

Synced from sferarc/pgbeam@d78ddfc

Author: SferaDev

openapi.json

@@ -0,0 +1,7 @@
+name: artifact_id
+in: path
+required: true
+description: Unique CRM artifact identifier (prefixed, e.g. art_xxx).
+schema:
+  type: string
+  pattern: ^[a-zA-Z0-9_.-]+$

openapi.yaml

@@ -0,0 +1,7 @@
+name: company_id
+in: path
+required: true
+description: Unique CRM company identifier (prefixed, e.g. cmp_xxx).
+schema:
+  type: string
+  pattern: ^[a-zA-Z0-9_.-]+$

spec/components/parameters/CrmArtifactId.yaml

@@ -0,0 +1,7 @@
+name: contact_id
+in: path
+required: true
+description: Unique CRM contact identifier (prefixed, e.g. cnt_xxx).
+schema:
+  type: string
+  pattern: ^[a-zA-Z0-9_.-]+$

spec/components/parameters/CrmCompanyId.yaml

@@ -0,0 +1,7 @@
+name: deal_id
+in: path
+required: true
+description: Unique CRM deal identifier (prefixed, e.g. dl_xxx).
+schema:
+  type: string
+  pattern: ^[a-zA-Z0-9_.-]+$

spec/components/parameters/CrmContactId.yaml

@@ -0,0 +1,7 @@
+name: task_id
+in: path
+required: true
+description: Unique CRM research task identifier (prefixed, e.g. ctk_xxx).
+schema:
+  type: string
+  pattern: ^[a-zA-Z0-9_.-]+$

spec/components/parameters/CrmDealId.yaml

@@ -0,0 +1,33 @@
+type: object
+description: A single entry in an entity's activity timeline.
+required:
+  - id
+  - org_id
+  - subject_type
+  - subject_id
+  - actor
+  - verb
+  - at
+properties:
+  id:
+    type: string
+    description: Unique activity identifier.
+    example: act_01j9x8y7z6w5v4u3t2s1r0q9p8
+  org_id:
+    type: string
+    description: Organization the activity belongs to.
+  subject_type:
+    $ref: ./ResearchTaskSubjectType.yaml
+  subject_id:
+    type: string
+    description: ID of the company/contact/deal this activity is about.
+  actor:
+    type: string
+    description: Who performed the action ("agent" or a user identifier).
+  verb:
+    type: string
+    description: What happened (created, enriched, drafted, approved, sent).
+  at:
+    type: string
+    format: date-time
+    description: When the action happened.

spec/components/parameters/CrmTaskId.yaml

@@ -0,0 +1,8 @@
+type: string
+description: >
+  Specialist agent role that owns a task. The researcher is the lead, the
+  enricher fills in graph edges, and outreach writes and sends.
+enum:
+  - researcher
+  - enricher
+  - outreach

spec/components/schemas/Activity.yaml

@@ -0,0 +1,49 @@
+type: object
+description: Long-form agent output (a drafted email, an account brief) for human review.
+required:
+  - id
+  - org_id
+  - subject_type
+  - subject_id
+  - kind
+  - title
+  - body
+  - status
+  - created_at
+  - updated_at
+properties:
+  id:
+    type: string
+    description: Unique artifact identifier.
+    example: art_01j9x8y7z6w5v4u3t2s1r0q9p8
+  org_id:
+    type: string
+    description: Organization the artifact belongs to.
+  task_id:
+    type: string
+    nullable: true
+    description: Research task that produced this artifact, if any.
+  subject_type:
+    $ref: ./ResearchTaskSubjectType.yaml
+  subject_id:
+    type: string
+    description: ID of the company/contact/deal this artifact is about.
+  kind:
+    type: string
+    description: Kind of artifact (e.g. outreach_email, account_brief).
+  title:
+    type: string
+    description: Short title.
+  body:
+    type: string
+    description: Long-form content.
+  status:
+    $ref: ./ArtifactStatus.yaml
+  created_at:
+    type: string
+    format: date-time
+    description: When the artifact was created.
+  updated_at:
+    type: string
+    format: date-time
+    description: When the artifact was last updated.