Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
feat: add contacts management and thread resolution (#957)
Acho Arnoldc2709f7db2e2
diff --git a/.mcp.json b/.mcp.jsonindex ef3d2cf0..d4cd9395 100644--- a/.mcp.json+++ b/.mcp.json@@ -1,27 +1,9 @@{"mcpServers": {- "playwright": {- "type": "stdio",- "command": "npx",- "args": [- "-y",- "@modelcontextprotocol/server-playwright",- "--base-url",- "http://localhost:3000"- ],- "env": {- "BROWSER": "chromium"- }- },"context7": {"type": "stdio","command": "npx","args": ["@upstash/context7-mcp@latest"]- },- "axiom": {- "type": "stdio",- "command": "npx",- "args": ["-y", "mcp-remote", "https://mcp.axiom.co/mcp"]}}}diff --git a/api/docs/docs.go b/api/docs/docs.goindex 8cd408cb..8eb6dafe 100644--- a/api/docs/docs.go+++ b/api/docs/docs.go@@ -242,6 +242,372 @@ const docTemplate = `{}}},+ "/contacts": {+ "get": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Returns the paginated list of contacts for the authenticated user. The top-level \"total\" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "List contacts",+ "parameters": [+ {+ "minimum": 0,+ "type": "integer",+ "description": "number of contacts to skip",+ "name": "skip",+ "in": "query"+ },+ {+ "type": "string",+ "description": "filter contacts containing query",+ "name": "query",+ "in": "query"+ },+ {+ "enum": [+ "name",+ "updated_at"+ ],+ "type": "string",+ "description": "field to sort contacts by",+ "name": "sort_by",+ "in": "query"+ },+ {+ "type": "boolean",+ "description": "sort contacts in descending order",+ "name": "sort_descending",+ "in": "query"+ },+ {+ "maximum": 100,+ "minimum": 1,+ "type": "integer",+ "description": "number of contacts to return",+ "name": "limit",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "OK",+ "schema": {+ "$ref": "#/definitions/responses.ContactsResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ },+ "post": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a \"contacts\" array.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Create one or many contacts",+ "parameters": [+ {+ "description": "Contact(s) to create",+ "name": "payload",+ "in": "body",+ "required": true,+ "schema": {+ "$ref": "#/definitions/requests.ContactStoreRequest"+ }+ }+ ],+ "responses": {+ "201": {+ "description": "Created",+ "schema": {+ "$ref": "#/definitions/responses.ContactsCreatedResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "402": {+ "description": "Payment Required",+ "schema": {+ "$ref": "#/definitions/responses.PaymentRequired"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },+ "/contacts/upload": {+ "post": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Uploads a CSV file (multipart field \"document\") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by \";\").",+ "consumes": [+ "multipart/form-data"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Import contacts from CSV",+ "parameters": [+ {+ "type": "file",+ "description": "CSV file of contacts",+ "name": "document",+ "in": "formData",+ "required": true+ }+ ],+ "responses": {+ "201": {+ "description": "Created",+ "schema": {+ "$ref": "#/definitions/responses.ContactsCreatedResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "402": {+ "description": "Payment Required",+ "schema": {+ "$ref": "#/definitions/responses.PaymentRequired"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },+ "/contacts/{contactID}": {+ "put": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Updates the details of a single contact.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Update a contact",+ "parameters": [+ {+ "type": "string",+ "description": "ID of the contact",+ "name": "contactID",+ "in": "path",+ "required": true+ },+ {+ "description": "Contact details to update",+ "name": "payload",+ "in": "body",+ "required": true,+ "schema": {+ "$ref": "#/definitions/requests.ContactUpdateRequest"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "OK",+ "schema": {+ "$ref": "#/definitions/responses.ContactResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ },+ "delete": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Deletes a single contact from the database.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Delete a contact",+ "parameters": [+ {+ "type": "string",+ "description": "ID of the contact",+ "name": "contactID",+ "in": "path",+ "required": true+ }+ ],+ "responses": {+ "204": {+ "description": "No Content",+ "schema": {+ "$ref": "#/definitions/responses.NoContent"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },"/discord-integrations": {"get": {"security": [@@ -794,6 +1160,12 @@ const docTemplate = `{"description": "number of messages to return","name": "limit","in": "query"+ },+ {+ "type": "boolean",+ "description": "include matching contact details",+ "name": "contacts",+ "in": "query"}],"responses": {@@ -3401,6 +3773,66 @@ const docTemplate = `{}}},+ "entities.Contact": {+ "type": "object",+ "required": [+ "created_at",+ "emails",+ "id",+ "name",+ "phone_numbers",+ "properties",+ "updated_at",+ "user_id"+ ],+ "properties": {+ "created_at": {+ "type": "string",+ "example": "2022-06-05T14:26:02.302718+03:00"+ },+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "example": [+ ]+ },+ "id": {+ "type": "string",+ "example": "32343a19-da5e-4b1b-a767-3298a73703cb"+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "example": [+ "+18005550199",+ "+18005550100"+ ]+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ "updated_at": {+ "type": "string",+ "example": "2022-06-05T14:26:02.302718+03:00"+ },+ "user_id": {+ "type": "string",+ "example": "WB7DRDWrJZRGbYrv2CKGkqbzvqdC"+ }+ }+ },"entities.Discord": {"type": "object","required": [@@ -3715,6 +4147,14 @@ const docTemplate = `{"type": "string","example": "+18005550100"},+ "contact_details": {+ "description": "ContactDetails is resolved at read time and never persisted.",+ "allOf": [+ {+ "$ref": "#/definitions/entities.Contact"+ }+ ]+ },"created_at": {"type": "string","example": "2022-06-05T14:26:09.527976+03:00"@@ -4080,6 +4520,82 @@ const docTemplate = `{}}},+ "requests.ContactItem": {+ "type": "object",+ "required": [+ "name",+ "phone_numbers"+ ],+ "properties": {+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ }+ }+ },+ "requests.ContactStoreRequest": {+ "type": "object",+ "required": [+ "contacts"+ ],+ "properties": {+ "contacts": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/requests.ContactItem"+ }+ }+ }+ },+ "requests.ContactUpdateRequest": {+ "type": "object",+ "required": [+ "name",+ "phone_numbers"+ ],+ "properties": {+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ }+ }+ },"requests.DiscordStore": {"type": "object","required": [@@ -4743,6 +5259,81 @@ const docTemplate = `{}}},+ "responses.ContactResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "$ref": "#/definitions/entities.Contact"+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },+ "responses.ContactsCreatedResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/entities.Contact"+ }+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },+ "responses.ContactsResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status",+ "total"+ ],+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/entities.Contact"+ }+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ },+ "total": {+ "description": "Total is the number of contacts matching the request filter for the\nuser, independent of the pagination skip/limit applied to Data.",+ "type": "integer",+ "example": 57+ }+ }+ },"responses.DiscordResponse": {"type": "object","required": [diff --git a/api/docs/swagger.json b/api/docs/swagger.jsonindex ac9c12c9..21c6bbf8 100644--- a/api/docs/swagger.json+++ b/api/docs/swagger.json@@ -239,6 +239,372 @@}}},+ "/contacts": {+ "get": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Returns the paginated list of contacts for the authenticated user. The top-level \"total\" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "List contacts",+ "parameters": [+ {+ "minimum": 0,+ "type": "integer",+ "description": "number of contacts to skip",+ "name": "skip",+ "in": "query"+ },+ {+ "type": "string",+ "description": "filter contacts containing query",+ "name": "query",+ "in": "query"+ },+ {+ "enum": [+ "name",+ "updated_at"+ ],+ "type": "string",+ "description": "field to sort contacts by",+ "name": "sort_by",+ "in": "query"+ },+ {+ "type": "boolean",+ "description": "sort contacts in descending order",+ "name": "sort_descending",+ "in": "query"+ },+ {+ "maximum": 100,+ "minimum": 1,+ "type": "integer",+ "description": "number of contacts to return",+ "name": "limit",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "OK",+ "schema": {+ "$ref": "#/definitions/responses.ContactsResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ },+ "post": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a \"contacts\" array.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Create one or many contacts",+ "parameters": [+ {+ "description": "Contact(s) to create",+ "name": "payload",+ "in": "body",+ "required": true,+ "schema": {+ "$ref": "#/definitions/requests.ContactStoreRequest"+ }+ }+ ],+ "responses": {+ "201": {+ "description": "Created",+ "schema": {+ "$ref": "#/definitions/responses.ContactsCreatedResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "402": {+ "description": "Payment Required",+ "schema": {+ "$ref": "#/definitions/responses.PaymentRequired"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },+ "/contacts/upload": {+ "post": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Uploads a CSV file (multipart field \"document\") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by \";\").",+ "consumes": [+ "multipart/form-data"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Import contacts from CSV",+ "parameters": [+ {+ "type": "file",+ "description": "CSV file of contacts",+ "name": "document",+ "in": "formData",+ "required": true+ }+ ],+ "responses": {+ "201": {+ "description": "Created",+ "schema": {+ "$ref": "#/definitions/responses.ContactsCreatedResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "402": {+ "description": "Payment Required",+ "schema": {+ "$ref": "#/definitions/responses.PaymentRequired"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },+ "/contacts/{contactID}": {+ "put": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Updates the details of a single contact.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Update a contact",+ "parameters": [+ {+ "type": "string",+ "description": "ID of the contact",+ "name": "contactID",+ "in": "path",+ "required": true+ },+ {+ "description": "Contact details to update",+ "name": "payload",+ "in": "body",+ "required": true,+ "schema": {+ "$ref": "#/definitions/requests.ContactUpdateRequest"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "OK",+ "schema": {+ "$ref": "#/definitions/responses.ContactResponse"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ },+ "delete": {+ "security": [+ {+ "ApiKeyAuth": []+ }+ ],+ "description": "Deletes a single contact from the database.",+ "consumes": [+ "application/json"+ ],+ "produces": [+ "application/json"+ ],+ "tags": [+ "Contacts"+ ],+ "summary": "Delete a contact",+ "parameters": [+ {+ "type": "string",+ "description": "ID of the contact",+ "name": "contactID",+ "in": "path",+ "required": true+ }+ ],+ "responses": {+ "204": {+ "description": "No Content",+ "schema": {+ "$ref": "#/definitions/responses.NoContent"+ }+ },+ "400": {+ "description": "Bad Request",+ "schema": {+ "$ref": "#/definitions/responses.BadRequest"+ }+ },+ "401": {+ "description": "Unauthorized",+ "schema": {+ "$ref": "#/definitions/responses.Unauthorized"+ }+ },+ "404": {+ "description": "Not Found",+ "schema": {+ "$ref": "#/definitions/responses.NotFound"+ }+ },+ "422": {+ "description": "Unprocessable Entity",+ "schema": {+ "$ref": "#/definitions/responses.UnprocessableEntity"+ }+ },+ "500": {+ "description": "Internal Server Error",+ "schema": {+ "$ref": "#/definitions/responses.InternalServerError"+ }+ }+ }+ }+ },"/discord-integrations": {"get": {"security": [@@ -791,6 +1157,12 @@"description": "number of messages to return","name": "limit","in": "query"+ },+ {+ "type": "boolean",+ "description": "include matching contact details",+ "name": "contacts",+ "in": "query"}],"responses": {@@ -3398,6 +3770,66 @@}}},+ "entities.Contact": {+ "type": "object",+ "required": [+ "created_at",+ "emails",+ "id",+ "name",+ "phone_numbers",+ "properties",+ "updated_at",+ "user_id"+ ],+ "properties": {+ "created_at": {+ "type": "string",+ "example": "2022-06-05T14:26:02.302718+03:00"+ },+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "example": [+ ]+ },+ "id": {+ "type": "string",+ "example": "32343a19-da5e-4b1b-a767-3298a73703cb"+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "example": [+ "+18005550199",+ "+18005550100"+ ]+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ "updated_at": {+ "type": "string",+ "example": "2022-06-05T14:26:02.302718+03:00"+ },+ "user_id": {+ "type": "string",+ "example": "WB7DRDWrJZRGbYrv2CKGkqbzvqdC"+ }+ }+ },"entities.Discord": {"type": "object","required": [@@ -3712,6 +4144,14 @@"type": "string","example": "+18005550100"},+ "contact_details": {+ "description": "ContactDetails is resolved at read time and never persisted.",+ "allOf": [+ {+ "$ref": "#/definitions/entities.Contact"+ }+ ]+ },"created_at": {"type": "string","example": "2022-06-05T14:26:09.527976+03:00"@@ -4077,6 +4517,82 @@}}},+ "requests.ContactItem": {+ "type": "object",+ "required": [+ "name",+ "phone_numbers"+ ],+ "properties": {+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ }+ }+ },+ "requests.ContactStoreRequest": {+ "type": "object",+ "required": [+ "contacts"+ ],+ "properties": {+ "contacts": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/requests.ContactItem"+ }+ }+ }+ },+ "requests.ContactUpdateRequest": {+ "type": "object",+ "required": [+ "name",+ "phone_numbers"+ ],+ "properties": {+ "emails": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "name": {+ "type": "string",+ "example": "Alice Smith"+ },+ "phone_numbers": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "properties": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ }+ }+ },"requests.DiscordStore": {"type": "object","required": [@@ -4740,6 +5256,81 @@}}},+ "responses.ContactResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "$ref": "#/definitions/entities.Contact"+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },+ "responses.ContactsCreatedResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status"+ ],+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/entities.Contact"+ }+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ }+ }+ },+ "responses.ContactsResponse": {+ "type": "object",+ "required": [+ "data",+ "message",+ "status",+ "total"+ ],+ "properties": {+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/definitions/entities.Contact"+ }+ },+ "message": {+ "type": "string",+ "example": "Request handled successfully"+ },+ "status": {+ "type": "string",+ "example": "success"+ },+ "total": {+ "description": "Total is the number of contacts matching the request filter for the\nuser, independent of the pagination skip/limit applied to Data.",+ "type": "integer",+ "example": 57+ }+ }+ },"responses.DiscordResponse": {"type": "object","required": [diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yamlindex ddc6ae70..4fe2f2b7 100644--- a/api/docs/swagger.yaml+++ b/api/docs/swagger.yaml@@ -80,6 +80,50 @@ definitions:- sent_count- totaltype: object+ entities.Contact:+ properties:+ created_at:+ example: "2022-06-05T14:26:02.302718+03:00"+ type: string+ emails:+ example:+ items:+ type: string+ type: array+ id:+ example: 32343a19-da5e-4b1b-a767-3298a73703cb+ type: string+ name:+ example: Alice Smith+ type: string+ phone_numbers:+ example:+ - "+18005550199"+ - "+18005550100"+ items:+ type: string+ type: array+ properties:+ additionalProperties:+ type: string+ type: object+ updated_at:+ example: "2022-06-05T14:26:02.302718+03:00"+ type: string+ user_id:+ example: WB7DRDWrJZRGbYrv2CKGkqbzvqdC+ type: string+ required:+ - created_at+ - emails+ - id+ - name+ - phone_numbers+ - properties+ - updated_at+ - user_id+ type: objectentities.Discord:properties:created_at:@@ -310,6 +354,10 @@ definitions:contact:example: "+18005550100"type: string+ contact_details:+ allOf:+ - $ref: '#/definitions/entities.Contact'+ description: ContactDetails is resolved at read time and never persisted.created_at:example: "2022-06-05T14:26:09.527976+03:00"type: string@@ -605,6 +653,57 @@ definitions:- url- user_idtype: object+ requests.ContactItem:+ properties:+ emails:+ items:+ type: string+ type: array+ name:+ example: Alice Smith+ type: string+ phone_numbers:+ items:+ type: string+ type: array+ properties:+ additionalProperties:+ type: string+ type: object+ required:+ - name+ - phone_numbers+ type: object+ requests.ContactStoreRequest:+ properties:+ contacts:+ items:+ $ref: '#/definitions/requests.ContactItem'+ type: array+ required:+ - contacts+ type: object+ requests.ContactUpdateRequest:+ properties:+ emails:+ items:+ type: string+ type: array+ name:+ example: Alice Smith+ type: string+ phone_numbers:+ items:+ type: string+ type: array+ properties:+ additionalProperties:+ type: string+ type: object+ required:+ - name+ - phone_numbers+ type: objectrequests.DiscordStore:properties:incoming_channel_id:@@ -1109,6 +1208,62 @@ definitions:- message- statustype: object+ responses.ContactResponse:+ properties:+ data:+ $ref: '#/definitions/entities.Contact'+ message:+ example: Request handled successfully+ type: string+ status:+ example: success+ type: string+ required:+ - data+ - message+ - status+ type: object+ responses.ContactsCreatedResponse:+ properties:+ data:+ items:+ $ref: '#/definitions/entities.Contact'+ type: array+ message:+ example: Request handled successfully+ type: string+ status:+ example: success+ type: string+ required:+ - data+ - message+ - status+ type: object+ responses.ContactsResponse:+ properties:+ data:+ items:+ $ref: '#/definitions/entities.Contact'+ type: array+ message:+ example: Request handled successfully+ type: string+ status:+ example: success+ type: string+ total:+ description: |-+ Total is the number of contacts matching the request filter for the+ user, independent of the pagination skip/limit applied to Data.+ example: 57+ type: integer+ required:+ - data+ - message+ - status+ - total+ type: objectresponses.DiscordResponse:properties:data:@@ -1747,6 +1902,247 @@ paths:summary: Store bulk SMS filetags:- BulkSMS+ /contacts:+ get:+ consumes:+ - application/json+ description: Returns the paginated list of contacts for the authenticated user.+ The top-level "total" field is the number of contacts matching the query filter,+ independent of skip/limit, so clients can drive server-side pagination.+ parameters:+ - description: number of contacts to skip+ in: query+ minimum: 0+ name: skip+ type: integer+ - description: filter contacts containing query+ in: query+ name: query+ type: string+ - description: field to sort contacts by+ enum:+ - name+ - updated_at+ in: query+ name: sort_by+ type: string+ - description: sort contacts in descending order+ in: query+ name: sort_descending+ type: boolean+ - description: number of contacts to return+ in: query+ maximum: 100+ minimum: 1+ name: limit+ type: integer+ produces:+ - application/json+ responses:+ "200":+ description: OK+ schema:+ $ref: '#/definitions/responses.ContactsResponse'+ "400":+ description: Bad Request+ schema:+ $ref: '#/definitions/responses.BadRequest'+ "401":+ description: Unauthorized+ schema:+ $ref: '#/definitions/responses.Unauthorized'+ "422":+ description: Unprocessable Entity+ schema:+ $ref: '#/definitions/responses.UnprocessableEntity'+ "500":+ description: Internal Server Error+ schema:+ $ref: '#/definitions/responses.InternalServerError'+ security:+ - ApiKeyAuth: []+ summary: List contacts+ tags:+ - Contacts+ post:+ consumes:+ - application/json+ description: Creates a single contact or a batch of contacts. Accepts a JSON+ array or an object with a "contacts" array.+ parameters:+ - description: Contact(s) to create+ in: body+ name: payload+ required: true+ schema:+ $ref: '#/definitions/requests.ContactStoreRequest'+ produces:+ - application/json+ responses:+ "201":+ description: Created+ schema:+ $ref: '#/definitions/responses.ContactsCreatedResponse'+ "400":+ description: Bad Request+ schema:+ $ref: '#/definitions/responses.BadRequest'+ "401":+ description: Unauthorized+ schema:+ $ref: '#/definitions/responses.Unauthorized'+ "402":+ description: Payment Required+ schema:+ $ref: '#/definitions/responses.PaymentRequired'+ "422":+ description: Unprocessable Entity+ schema:+ $ref: '#/definitions/responses.UnprocessableEntity'+ "500":+ description: Internal Server Error+ schema:+ $ref: '#/definitions/responses.InternalServerError'+ security:+ - ApiKeyAuth: []+ summary: Create one or many contacts+ tags:+ - Contacts+ /contacts/{contactID}:+ delete:+ consumes:+ - application/json+ description: Deletes a single contact from the database.+ parameters:+ - description: ID of the contact+ in: path+ name: contactID+ required: true+ type: string+ produces:+ - application/json+ responses:+ "204":+ description: No Content+ schema:+ $ref: '#/definitions/responses.NoContent'+ "400":+ description: Bad Request+ schema:+ $ref: '#/definitions/responses.BadRequest'+ "401":+ description: Unauthorized+ schema:+ $ref: '#/definitions/responses.Unauthorized'+ "404":+ description: Not Found+ schema:+ $ref: '#/definitions/responses.NotFound'+ "422":+ description: Unprocessable Entity+ schema:+ $ref: '#/definitions/responses.UnprocessableEntity'+ "500":+ description: Internal Server Error+ schema:+ $ref: '#/definitions/responses.InternalServerError'+ security:+ - ApiKeyAuth: []+ summary: Delete a contact+ tags:+ - Contacts+ put:+ consumes:+ - application/json+ description: Updates the details of a single contact.+ parameters:+ - description: ID of the contact+ in: path+ name: contactID+ required: true+ type: string+ - description: Contact details to update+ in: body+ name: payload+ required: true+ schema:+ $ref: '#/definitions/requests.ContactUpdateRequest'+ produces:+ - application/json+ responses:+ "200":+ description: OK+ schema:+ $ref: '#/definitions/responses.ContactResponse'+ "400":+ description: Bad Request+ schema:+ $ref: '#/definitions/responses.BadRequest'+ "401":+ description: Unauthorized+ schema:+ $ref: '#/definitions/responses.Unauthorized'+ "404":+ description: Not Found+ schema:+ $ref: '#/definitions/responses.NotFound'+ "422":+ description: Unprocessable Entity+ schema:+ $ref: '#/definitions/responses.UnprocessableEntity'+ "500":+ description: Internal Server Error+ schema:+ $ref: '#/definitions/responses.InternalServerError'+ security:+ - ApiKeyAuth: []+ summary: Update a contact+ tags:+ - Contacts+ /contacts/upload:+ post:+ consumes:+ - multipart/form-data+ description: 'Uploads a CSV file (multipart field "document") of contacts. Columns:+ Name, Emails, PhoneNumbers (multi-values separated by ";").'+ parameters:+ - description: CSV file of contacts+ in: formData+ name: document+ required: true+ type: file+ produces:+ - application/json+ responses:+ "201":+ description: Created+ schema:+ $ref: '#/definitions/responses.ContactsCreatedResponse'+ "400":+ description: Bad Request+ schema:+ $ref: '#/definitions/responses.BadRequest'+ "401":+ description: Unauthorized+ schema:+ $ref: '#/definitions/responses.Unauthorized'+ "402":+ description: Payment Required+ schema:+ $ref: '#/definitions/responses.PaymentRequired'+ "422":+ description: Unprocessable Entity+ schema:+ $ref: '#/definitions/responses.UnprocessableEntity'+ "500":+ description: Internal Server Error+ schema:+ $ref: '#/definitions/responses.InternalServerError'+ security:+ - ApiKeyAuth: []+ summary: Import contacts from CSV+ tags:+ - Contacts/discord-integrations:get:consumes:@@ -2106,6 +2502,10 @@ paths:minimum: 1name: limittype: integer+ - description: include matching contact details+ in: query+ name: contacts+ type: booleanproduces:- application/jsonresponses:diff --git a/api/pkg/di/container.go b/api/pkg/di/container.goindex ad9a1885..ebe57662 100644--- a/api/pkg/di/container.go+++ b/api/pkg/di/container.go@@ -84,18 +84,20 @@ import (// Container is used to resolve services at runtimetype Container struct {- projectID string- db *gorm.DB- dedicatedDB *gorm.DB- mongoDB *mongoDriver.Database- version string- app *fiber.App- eventDispatcher *services.EventDispatcher- logger telemetry.Logger- attachmentRepository repositories.AttachmentRepository- userRistrettoCache *ristretto.Cache[string, entities.AuthContext]- phoneRistrettoCache *ristretto.Cache[string, *entities.Phone]- inMemoryCache cache.Cache+ projectID string+ db *gorm.DB+ dedicatedDB *gorm.DB+ mongoDB *mongoDriver.Database+ version string+ app *fiber.App+ eventDispatcher *services.EventDispatcher+ logger telemetry.Logger+ attachmentRepository repositories.AttachmentRepository+ contactService *services.ContactService+ userRistrettoCache *ristretto.Cache[string, entities.AuthContext]+ phoneRistrettoCache *ristretto.Cache[string, *entities.Phone]+ contactRistrettoCache *ristretto.Cache[string, services.ContactCacheEntry]+ inMemoryCache cache.Cache}// NewLiteContainer creates a Container without any routes or listeners@@ -123,6 +125,9 @@ func NewContainer(projectID string, version string) (container *Container) {container.RegisterMessageThreadRoutes()container.RegisterMessageThreadListeners()+ container.RegisterContactRoutes()+ container.RegisterContactListeners()+container.RegisterHeartbeatRoutes()container.RegisterHeartbeatListeners()@@ -414,6 +419,10 @@ ALTER TABLE discords ADD CONSTRAINT IF NOT EXISTS uni_discords_server_id CHECK (container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.PhoneAPIKey{}))}+ if err = db.AutoMigrate(&entities.Contact{}); err != nil {+ container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))+ }+return container.db}@@ -579,7 +588,6 @@ func (container *Container) MessageHandlerValidator() (validator *validators.Mescontainer.Tracer(),container.PhoneService(),container.TurnstileTokenValidator(),- container.Cache(),)}@@ -602,7 +610,6 @@ func (container *Container) BulkMessageHandlerValidator() (validator *validatorscontainer.Tracer(),container.PhoneService(),container.UserService(),- container.Cache(),)}@@ -697,6 +704,27 @@ func (container *Container) MessageThreadHandlerValidator() (validator *validato)}+// ContactHandlerValidator creates a new instance of validators.ContactHandlerValidator+func (container *Container) ContactHandlerValidator() (validator *validators.ContactHandlerValidator) {+ container.logger.Debug(fmt.Sprintf("creating %T", validator))+ return validators.NewContactHandlerValidator(+ container.Logger(),+ container.Tracer(),+ )+}++// ContactHandler creates a new instance of handlers.ContactHandler+func (container *Container) ContactHandler() (h *handlers.ContactHandler) {+ container.logger.Debug(fmt.Sprintf("creating %T", h))+ return handlers.NewContactHandler(+ container.Logger(),+ container.Tracer(),+ container.ContactHandlerValidator(),+ container.ContactService(),+ container.EntitlementService(),+ )+}+// PhoneHandlerValidator creates a new instance of validators.PhoneHandlerValidatorfunc (container *Container) PhoneHandlerValidator() (validator *validators.PhoneHandlerValidator) {container.logger.Debug(fmt.Sprintf("creating %T", validator))@@ -895,6 +923,26 @@ func (container *Container) MessageThreadRepository() (repository repositories.M)}+// ContactRepository creates a new instance of repositories.ContactRepository+func (container *Container) ContactRepository() (repository repositories.ContactRepository) {+ switch os.Getenv("CONTACT_DB_BACKEND") {+ case "mongodb":+ container.logger.Debug("creating MongoDB repositories.ContactRepository")+ return repositories.NewMongoContactRepository(+ container.Logger(),+ container.Tracer(),+ container.MongoDB(),+ )+ default:+ container.logger.Debug("creating GORM repositories.ContactRepository")+ return repositories.NewGormContactRepository(+ container.Logger(),+ container.Tracer(),+ container.DB(),+ )+ }+}+// HeartbeatMonitorRepository creates a new instance of repositories.HeartbeatMonitorRepositoryfunc (container *Container) HeartbeatMonitorRepository() (repository repositories.HeartbeatMonitorRepository) {switch os.Getenv("HEARTBEAT_DB_BACKEND") {@@ -1110,7 +1158,23 @@ func (container *Container) MessageThreadService() (service *services.MessageThrcontainer.MessageThreadRepository(),container.PhoneRepository(),container.EventDispatcher(),+ container.ContactService(),+ )+}++// ContactService creates a new instance of services.ContactService+func (container *Container) ContactService() (service *services.ContactService) {+ if container.contactService != nil {+ return container.contactService+ }+ container.logger.Debug(fmt.Sprintf("creating %T", service))+ container.contactService = services.NewContactService(+ container.Logger(),+ container.Tracer(),+ container.ContactRepository(),+ container.ContactRistrettoCache(),)+ return container.contactService}// EmailNotificationService creates a new instance of services.EmailNotificationService@@ -1374,6 +1438,20 @@ func (container *Container) RegisterMessageThreadListeners() {}}+// RegisterContactListeners registers event listeners for listeners.ContactListener.+func (container *Container) RegisterContactListeners() {+ container.logger.Debug(fmt.Sprintf("registering listeners for %T", listeners.ContactListener{}))+ _, routes := listeners.NewContactListener(+ container.Logger(),+ container.Tracer(),+ container.ContactService(),+ )++ for event, handler := range routes {+ container.EventDispatcher().Subscribe(event, handler)+ }+}+// RegisterEmailNotificationListeners registers event listeners for listeners.EmailNotificationListenerfunc (container *Container) RegisterEmailNotificationListeners() {container.logger.Debug(fmt.Sprintf("registering listners for %T", listeners.EmailNotificationListener{}))@@ -1664,6 +1742,12 @@ func (container *Container) RegisterMessageThreadRoutes() {container.MessageThreadHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())}+// RegisterContactRoutes registers routes for the /contacts prefix+func (container *Container) RegisterContactRoutes() {+ container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.ContactHandler{}))+ container.ContactHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())+}+// RegisterHeartbeatRoutes registers routes for the /heartbeats prefixfunc (container *Container) RegisterHeartbeatRoutes() {container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.HeartbeatHandler{}))@@ -1773,6 +1857,24 @@ func (container *Container) PhoneRistrettoCache() *ristretto.Cache[string, *entireturn container.phoneRistrettoCache}+// ContactRistrettoCache creates an in-memory cache keyed by user and phone number.+func (container *Container) ContactRistrettoCache() *ristretto.Cache[string, services.ContactCacheEntry] {+ if container.contactRistrettoCache != nil {+ return container.contactRistrettoCache+ }+ container.logger.Debug(fmt.Sprintf("creating %T", container.contactRistrettoCache))+ ristrettoCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{+ MaxCost: 5000,+ NumCounters: 5000 * 10,+ BufferItems: 64,+ })+ if err != nil {+ container.logger.Fatal(stacktrace.Propagatef(err, "cannot create contact ristretto cache"))+ }+ container.contactRistrettoCache = ristrettoCache+ return container.contactRistrettoCache+}+// UserRistrettoCache creates an in-memory *ristretto.Cache[string, entities.AuthContext]func (container *Container) UserRistrettoCache() *ristretto.Cache[string, entities.AuthContext] {if container.userRistrettoCache != nil {diff --git a/api/pkg/entities/contact.go b/api/pkg/entities/contact.gonew file mode 100644index 00000000..71723bf1--- /dev/null+++ b/api/pkg/entities/contact.go@@ -0,0 +1,79 @@+package entities++import (+ "database/sql/driver"+ "encoding/json"+ "time"++ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "github.com/lib/pq"+)++// EntityNameContact is the entitlement entity name for contacts.+const EntityNameContact = "Contact"++// ContactProperties is a free-form key/value map persisted as a jsonb column.+type ContactProperties map[string]string++// Value implements driver.Valuer, serializing the map to JSON bytes.+func (p ContactProperties) Value() (driver.Value, error) {+ if p == nil {+ return []byte("{}"), nil+ }++ data, err := json.Marshal(p)+ if err != nil {+ return nil, stacktrace.Propagatef(err, "cannot marshal ContactProperties")+ }++ return data, nil+}++// Scan implements sql.Scanner, deserializing jsonb bytes/string into the map.+func (p *ContactProperties) Scan(src any) error {+ if src == nil {+ *p = ContactProperties{}+ return nil+ }++ var data []byte+ switch value := src.(type) {+ case []byte:+ data = value+ case string:+ data = []byte(value)+ default:+ return stacktrace.NewErrorf("unsupported type [%T] for ContactProperties", src)+ }++ if len(data) == 0 {+ *p = ContactProperties{}+ return nil+ }++ result := ContactProperties{}+ if err := json.Unmarshal(data, &result); err != nil {+ return stacktrace.Propagatef(err, "cannot unmarshal ContactProperties")+ }++ *p = result+ return nil+}++// Contact represents a saved contact belonging to a user.+type Contact struct {+ ID uuid.UUID `json:"id" gorm:"primaryKey;type:uuid" bson:"_id" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`+ UserID UserID `json:"user_id" gorm:"index" bson:"user_id" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`+ Name string `json:"name" bson:"name" example:"Alice Smith"`+ Emails pq.StringArray `json:"emails" gorm:"type:text[]" bson:"emails" swaggertype:"array,string" example:"[email protected]"`+ PhoneNumbers pq.StringArray `json:"phone_numbers" gorm:"type:text[]" bson:"phone_numbers" swaggertype:"array,string" example:"+18005550199,+18005550100"`+ Properties ContactProperties `json:"properties" gorm:"type:jsonb" bson:"properties" swaggertype:"object,string"`+ CreatedAt time.Time `json:"created_at" bson:"created_at" example:"2022-06-05T14:26:02.302718+03:00"`+ UpdatedAt time.Time `json:"updated_at" bson:"updated_at" example:"2022-06-05T14:26:02.302718+03:00"`+}++// TableName overrides the table name used by Contact.+func (Contact) TableName() string {+ return "contacts"+}diff --git a/api/pkg/entities/contact_test.go b/api/pkg/entities/contact_test.gonew file mode 100644index 00000000..fa921840--- /dev/null+++ b/api/pkg/entities/contact_test.go@@ -0,0 +1,71 @@+package entities++import (+ "reflect"+ "testing"++ "github.com/stretchr/testify/assert"+)++func TestContact_BSONFieldNames(t *testing.T) {+ contactType := reflect.TypeOf(Contact{})+ expected := map[string]string{+ "ID": "_id",+ "UserID": "user_id",+ "Name": "name",+ "Emails": "emails",+ "PhoneNumbers": "phone_numbers",+ "Properties": "properties",+ "CreatedAt": "created_at",+ "UpdatedAt": "updated_at",+ }++ for fieldName, bsonName := range expected {+ field, found := contactType.FieldByName(fieldName)+ assert.True(t, found)+ assert.Equal(t, bsonName, field.Tag.Get("bson"))+ }+}++func TestContactProperties_ValueScanRoundTrip(t *testing.T) {+ cases := []ContactProperties{+ nil,+ {},+ {"company": "Acme", "role": "CTO"},+ }++ for _, original := range cases {+ value, err := original.Value()+ assert.Nil(t, err)++ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(value))++ if len(original) == 0 {+ assert.Equal(t, 0, len(scanned))+ continue+ }+ assert.Equal(t, original, scanned)+ }+}++func TestContactProperties_ScanFromString(t *testing.T) {+ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(`{"k":"v"}`))+ assert.Equal(t, ContactProperties{"k": "v"}, scanned)+}++func TestContactProperties_ScanNil(t *testing.T) {+ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(nil))+ assert.Equal(t, 0, len(scanned))+}++func TestContactProperties_ScanUnsupportedType(t *testing.T) {+ var scanned ContactProperties++ err := scanned.Scan(123)++ assert.Error(t, err)+ assert.Contains(t, err.Error(), "unsupported type [int] for ContactProperties")+}diff --git a/api/pkg/entities/message_thread.go b/api/pkg/entities/message_thread.goindex 3766acc7..d4d893a4 100644--- a/api/pkg/entities/message_thread.go+++ b/api/pkg/entities/message_thread.go@@ -22,6 +22,8 @@ type MessageThread struct {CreatedAt time.Time `json:"created_at" example:"2022-06-05T14:26:09.527976+03:00"`UpdatedAt time.Time `json:"updated_at" example:"2022-06-05T14:26:09.527976+03:00"`OrderTimestamp time.Time `json:"order_timestamp" example:"2022-06-05T14:26:09.527976+03:00"`+ // ContactDetails is resolved at read time and never persisted.+ ContactDetails *Contact `json:"contact_details,omitempty" gorm:"-"`}// Update a message thread after a message eventdiff --git a/api/pkg/entities/message_thread_test.go b/api/pkg/entities/message_thread_test.goindex 1409dff2..b587bacb 100644--- a/api/pkg/entities/message_thread_test.go+++ b/api/pkg/entities/message_thread_test.go@@ -1,6 +1,7 @@package entitiesimport (+ "encoding/json""reflect""testing"@@ -23,3 +24,20 @@ func TestMessageThreadReadFieldsHaveBackwardCompatibleDefaults(t *testing.T) {assert.Contains(t, lastReadAt.Tag.Get("gorm"), "default:CURRENT_TIMESTAMP")assert.Equal(t, "-", lastReadAt.Tag.Get("json"))}++func TestMessageThreadContactDetailsAreTransientAndOmittedWhenNil(t *testing.T) {+ threadType := reflect.TypeOf(MessageThread{})++ contactDetails, ok := threadType.FieldByName("ContactDetails")+ require.True(t, ok)+ assert.Equal(t, "*entities.Contact", contactDetails.Type.String())+ assert.Equal(t, "contact_details,omitempty", contactDetails.Tag.Get("json"))+ assert.Equal(t, "-", contactDetails.Tag.Get("gorm"))++ data, err := json.Marshal(MessageThread{})+ require.NoError(t, err)++ var payload map[string]any+ require.NoError(t, json.Unmarshal(data, &payload))+ assert.NotContains(t, payload, "contact_details")+}diff --git a/api/pkg/handlers/contact_handler.go b/api/pkg/handlers/contact_handler.gonew file mode 100644index 00000000..096a802e--- /dev/null+++ b/api/pkg/handlers/contact_handler.go@@ -0,0 +1,322 @@+package handlers++import (+ "context"+ "fmt"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/httpsms/pkg/validators"+ "github.com/NdoleStudio/stacktrace"+ "github.com/davecgh/go-spew/spew"+ "github.com/gofiber/fiber/v3"+ "github.com/google/uuid"+)++// ContactHandler handles contact http requests.+type ContactHandler struct {+ handler+ logger telemetry.Logger+ tracer telemetry.Tracer+ validator *validators.ContactHandlerValidator+ service *services.ContactService+ entitlementService *services.EntitlementService+}++// NewContactHandler creates a new ContactHandler.+func NewContactHandler(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ validator *validators.ContactHandlerValidator,+ service *services.ContactService,+ entitlementService *services.EntitlementService,+) (h *ContactHandler) {+ return &ContactHandler{+ logger: logger.WithService(fmt.Sprintf("%T", h)),+ tracer: tracer,+ validator: validator,+ service: service,+ entitlementService: entitlementService,+ }+}++// RegisterRoutes registers the routes for the ContactHandler.+func (h *ContactHandler) RegisterRoutes(router fiber.Router, middlewares ...fiber.Handler) {+ h.register(router, fiber.MethodGet, "/v1/contacts", middlewares, h.Index)+ h.register(router, fiber.MethodPost, "/v1/contacts", middlewares, h.Store)+ h.register(router, fiber.MethodPost, "/v1/contacts/upload", middlewares, h.Upload)+ h.register(router, fiber.MethodPut, "/v1/contacts/:contactID", middlewares, h.Update)+ h.register(router, fiber.MethodDelete, "/v1/contacts/:contactID", middlewares, h.Delete)+}++// Index lists contacts for the authenticated user.+// @Summary List contacts+// @Description Returns the paginated list of contacts for the authenticated user. The top-level "total" field is the number of contacts matching the query filter, independent of skip/limit, so clients can drive server-side pagination.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param skip query int false "number of contacts to skip" minimum(0)+// @Param query query string false "filter contacts containing query"+// @Param sort_by query string false "field to sort contacts by" Enums(name, updated_at)+// @Param sort_descending query bool false "sort contacts in descending order"+// @Param limit query int false "number of contacts to return" minimum(1) maximum(100)+// @Success 200 {object} responses.ContactsResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts [get]+func (h *ContactHandler) Index(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ var request requests.ContactIndex+ if err := c.Bind().Query(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall params [%s] into %T", c.OriginalURL(), request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateIndex(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while listing contacts [%+#v]", spew.Sdump(errors), sanitized))+ return h.responseUnprocessableEntity(c, errors, "validation errors while listing contacts")+ }++ userID := h.userIDFomContext(c)+ params := sanitized.ToIndexParams()+ contacts, err := h.service.Index(ctx, userID, params)+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot list contacts for user [%s]", userID))+ return h.responseInternalServerError(c)+ }++ total, err := h.service.Count(ctx, userID, params)+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot count contacts for user [%s]", userID))+ return h.responseInternalServerError(c)+ }++ return h.responseOKWithTotal(c, fmt.Sprintf("fetched %d %s", len(*contacts), h.pluralize("contact", len(*contacts))), contacts, total)+}++// Store creates one or many contacts.+// @Summary Create one or many contacts+// @Description Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a "contacts" array.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param payload body requests.ContactStoreRequest true "Contact(s) to create"+// @Success 201 {object} responses.ContactsCreatedResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 402 {object} responses.PaymentRequired+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts [post]+func (h *ContactHandler) Store(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ var request requests.ContactStoreRequest+ if err := c.Bind().Body(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body [%s] into %T", c.Body(), request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateStore(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while creating contacts", spew.Sdump(errors)))+ return h.responseUnprocessableEntity(c, errors, "validation errors while creating contacts")+ }++ userID := h.userIDFomContext(c)+ contacts := sanitized.ToContacts(userID)+ result, err := h.checkCreateEntitlement(ctx, userID, len(contacts))+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot check contact entitlement for user [%s]", userID))+ return h.responseInternalServerError(c)+ }+ if !result.Allowed {+ return h.responsePaymentRequired(c, result.Message)+ }++ if err := h.service.CreateMany(ctx, userID, contacts); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot create [%d] contacts for user [%s]", len(contacts), userID))+ return h.responseInternalServerError(c)+ }++ return h.responseCreated(c, fmt.Sprintf("created %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)+}++// Upload imports contacts from a CSV file.+// @Summary Import contacts from CSV+// @Description Uploads a CSV file (multipart field "document") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by ";").+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept multipart/form-data+// @Produce json+// @Param document formData file true "CSV file of contacts"+// @Success 201 {object} responses.ContactsCreatedResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 402 {object} responses.PaymentRequired+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/upload [post]+func (h *ContactHandler) Upload(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ file, err := c.FormFile("document")+ if err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot fetch file with name [%s] from request", "document"))+ return h.responseBadRequest(c, err)+ }++ userID := h.userIDFomContext(c)+ items, errors := h.validator.ValidateUpload(ctx, userID, file)+ if len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while importing contacts from CSV [%s]", spew.Sdump(errors), file.Filename))+ return h.responseUnprocessableEntity(c, errors, "validation errors while importing contacts")+ }++ // items are already sanitized by ValidateUpload (SanitizeContactItem), so+ // build the persistable records directly without re-sanitizing.+ request := requests.ContactStoreRequest{Contacts: items}+ contacts := request.ToContacts(userID)+ result, err := h.checkCreateEntitlement(ctx, userID, len(contacts))+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot check contact entitlement for user [%s]", userID))+ return h.responseInternalServerError(c)+ }+ if !result.Allowed {+ return h.responsePaymentRequired(c, result.Message)+ }++ if err = h.service.CreateMany(ctx, userID, contacts); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot import [%d] contacts for user [%s]", len(contacts), userID))+ return h.responseInternalServerError(c)+ }++ return h.responseCreated(c, fmt.Sprintf("imported %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)+}++// Update updates a single contact.+// @Summary Update a contact+// @Description Updates the details of a single contact.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param contactID path string true "ID of the contact"+// @Param payload body requests.ContactUpdateRequest true "Contact details to update"+// @Success 200 {object} responses.ContactResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 404 {object} responses.NotFound+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/{contactID} [put]+func (h *ContactHandler) Update(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ contactID := c.Params("contactID")+ if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")+ }++ var request requests.ContactUpdateRequest+ if err := c.Bind().Body(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body into %T", request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateUpdate(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")+ }++ userID := h.userIDFomContext(c)+ contact, err := h.service.Get(ctx, userID, uuid.MustParse(contactID))+ if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))+ }+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ previousPhoneNumbers := append([]string{}, contact.PhoneNumbers...)+ sanitized.ApplyTo(contact)+ if err = h.service.Update(ctx, contact, previousPhoneNumbers); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot update contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ return h.responseOK(c, "contact updated successfully", contact)+}++// Delete removes a single contact.+// @Summary Delete a contact+// @Description Deletes a single contact from the database.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param contactID path string true "ID of the contact"+// @Success 204 {object} responses.NoContent+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 404 {object} responses.NotFound+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/{contactID} [delete]+func (h *ContactHandler) Delete(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ contactID := c.Params("contactID")+ if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while deleting contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while deleting contact")+ }++ userID := h.userIDFomContext(c)++ // Load first so a missing contact for the authenticated user returns 404+ // instead of silently succeeding via a 0-row DELETE. This also prevents+ // leaking whether another user's contact exists.+ if _, err := h.service.Get(ctx, userID, uuid.MustParse(contactID)); err != nil {+ if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))+ }+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ if err := h.service.Delete(ctx, userID, uuid.MustParse(contactID)); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ return h.responseNoContent(c, "contact deleted successfully")+}++func (h *ContactHandler) checkCreateEntitlement(+ ctx context.Context,+ userID entities.UserID,+ additionalCount int,+) (*services.EntitlementCheckResult, error) {+ return h.entitlementService.CheckAdditional(ctx, userID, entities.EntityNameContact, additionalCount, func() (int, error) {+ count, err := h.service.Count(ctx, userID, repositories.IndexParams{})+ return int(count), err+ })+}diff --git a/api/pkg/handlers/contact_handler_test.go b/api/pkg/handlers/contact_handler_test.gonew file mode 100644index 00000000..5229cfad--- /dev/null+++ b/api/pkg/handlers/contact_handler_test.go@@ -0,0 +1,658 @@+package handlers++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "mime/multipart"+ "net/http"+ "net/http/httptest"+ "net/textproto"+ "net/url"+ "sync"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/middlewares"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/httpsms/pkg/validators"+ "github.com/NdoleStudio/stacktrace"+ "github.com/dgraph-io/ristretto/v2"+ "github.com/gofiber/fiber/v3"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "gorm.io/gorm"+)++// contactHandlerFakeRepo is a shared, thread-safe ContactRepository stub that+// records the effects of Store/Update/Delete and returns configurable Load/Index+// results so handler tests can assert real service→repository behaviour.+type contactHandlerFakeRepo struct {+ mu sync.Mutex++ stored [][]*entities.Contact+ updated []*entities.Contact+ deleted []deletedContact+ indexParams []repositories.IndexParams+ countParams []repositories.IndexParams+ loadCalls []loadedContact++ loadResult *entities.Contact+ loadErr error+ indexResult []entities.Contact+ indexErr error+ countResult int64+ countErr error+ storeErr error+ updateErr error+ deleteErr error+}++type deletedContact struct {+ userID entities.UserID+ id uuid.UUID+}++type loadedContact struct {+ userID entities.UserID+ id uuid.UUID+}++func (r *contactHandlerFakeRepo) Store(_ context.Context, contacts []*entities.Contact) error {+ r.mu.Lock()+ defer r.mu.Unlock()+ if r.storeErr != nil {+ return r.storeErr+ }+ r.stored = append(r.stored, contacts)+ return nil+}++func (r *contactHandlerFakeRepo) Update(_ context.Context, contact *entities.Contact) error {+ r.mu.Lock()+ defer r.mu.Unlock()+ if r.updateErr != nil {+ return r.updateErr+ }+ r.updated = append(r.updated, contact)+ return nil+}++func (r *contactHandlerFakeRepo) Load(_ context.Context, userID entities.UserID, id uuid.UUID) (*entities.Contact, error) {+ r.mu.Lock()+ defer r.mu.Unlock()+ r.loadCalls = append(r.loadCalls, loadedContact{userID: userID, id: id})+ if r.loadErr != nil {+ return nil, r.loadErr+ }+ if r.loadResult == nil {+ return nil, nil+ }+ // Return a copy so handler mutations don't corrupt the fixture.+ clone := *r.loadResult+ return &clone, nil+}++func (r *contactHandlerFakeRepo) Index(_ context.Context, _ entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {+ r.mu.Lock()+ defer r.mu.Unlock()+ r.indexParams = append(r.indexParams, params)+ if r.indexErr != nil {+ return nil, r.indexErr+ }+ out := make([]entities.Contact, len(r.indexResult))+ copy(out, r.indexResult)+ return &out, nil+}++func (r *contactHandlerFakeRepo) Count(_ context.Context, _ entities.UserID, params repositories.IndexParams) (int64, error) {+ r.mu.Lock()+ defer r.mu.Unlock()+ r.countParams = append(r.countParams, params)+ if r.countErr != nil {+ return 0, r.countErr+ }+ return r.countResult, nil+}++func (r *contactHandlerFakeRepo) FetchByPhoneNumbers(context.Context, entities.UserID, []string) (*[]entities.Contact, error) {+ out := []entities.Contact{}+ return &out, nil+}++func (r *contactHandlerFakeRepo) Delete(_ context.Context, userID entities.UserID, id uuid.UUID) error {+ r.mu.Lock()+ defer r.mu.Unlock()+ if r.deleteErr != nil {+ return r.deleteErr+ }+ r.deleted = append(r.deleted, deletedContact{userID: userID, id: id})+ return nil+}++func (r *contactHandlerFakeRepo) DeleteAllForUser(context.Context, entities.UserID) error {+ return nil+}++// snapshot returns a safe read of the recorded effects.+func (r *contactHandlerFakeRepo) snapshot() ([][]*entities.Contact, []*entities.Contact, []deletedContact, []repositories.IndexParams) {+ r.mu.Lock()+ defer r.mu.Unlock()+ return r.stored, r.updated, r.deleted, r.indexParams+}++const contactHandlerTestUserID = entities.UserID("user-id")++type contactHandlerEntitlementUserRepo struct {+ repositories.UserRepository+ subscriptionName entities.SubscriptionName+}++func (repository *contactHandlerEntitlementUserRepo) Load(_ context.Context, userID entities.UserID) (*entities.User, error) {+ return &entities.User{ID: userID, SubscriptionName: repository.subscriptionName}, nil+}++func newContactHandlerTestApp(repo repositories.ContactRepository) *fiber.App {+ return newContactHandlerTestAppWithEntitlements(repo, false, entities.SubscriptionNameFree)+}++func newContactHandlerTestAppWithEntitlements(+ repo repositories.ContactRepository,+ entitlementsEnabled bool,+ subscriptionName entities.SubscriptionName,+) *fiber.App {+ logger := &messageThreadHandlerNoopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ contactCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{+ MaxCost: 100, NumCounters: 1_000, BufferItems: 64,+ })+ if err != nil {+ panic(err)+ }+ service := services.NewContactService(logger, tracer, repo, contactCache)+ entitlementService := services.NewEntitlementService(+ logger,+ tracer,+ entitlementsEnabled,+ &contactHandlerEntitlementUserRepo{subscriptionName: subscriptionName},+ )+ handler := NewContactHandler(logger, tracer, validators.NewContactHandlerValidator(logger, tracer), service, entitlementService)++ app := fiber.New()+ app.Use(func(c fiber.Ctx) error {+ c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: contactHandlerTestUserID, Email: "[email protected]"})+ return c.Next()+ })+ handler.RegisterRoutes(app)+ return app+}++type contactHandlerPayload struct {+ Status string `json:"status"`+ Message string `json:"message"`+ Data json.RawMessage `json:"data"`+ Total int64 `json:"total"`+}++func decodeContactHandlerPayload(t *testing.T, resp *http.Response) contactHandlerPayload {+ t.Helper()+ var payload contactHandlerPayload+ require.NoError(t, json.NewDecoder(resp.Body).Decode(&payload))+ return payload+}++func TestContactHandler_Store_CreatesSingleContact(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ body := `[{"name":"Alice","phone_numbers":["+18005550199"],"emails":["[email protected]"]}]`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Len(t, stored, 1)+ require.Len(t, stored[0], 1)+ require.Equal(t, "Alice", stored[0][0].Name)+ require.Equal(t, contactHandlerTestUserID, stored[0][0].UserID)+ require.Equal(t, pq.StringArray{"+18005550199"}, stored[0][0].PhoneNumbers)+}++func TestContactHandler_Store_CreatesManyContactsFromObjectShape(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ body := `{"contacts":[+ {"name":"Alice","phone_numbers":["+18005550199"]},+ {"name":"Bob","phone_numbers":["+18005550100"]}+ ]}`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Len(t, stored, 1)+ require.Len(t, stored[0], 2)+ assert.Equal(t, "Alice", stored[0][0].Name)+ assert.Equal(t, "Bob", stored[0][1].Name)+}++func TestContactHandler_Store_RejectsBatchExceedingContactLimit(t *testing.T) {+ repo := &contactHandlerFakeRepo{countResult: 199}+ app := newContactHandlerTestAppWithEntitlements(repo, true, entities.SubscriptionNameFree)++ body := `{"contacts":[+ {"name":"Alice","phone_numbers":["+18005550199"]},+ {"name":"Bob","phone_numbers":["+18005550100"]}+ ]}`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusPaymentRequired, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ assert.Empty(t, stored)+}++func TestContactHandler_Store_DisabledEntitlementsDoNotLimitContacts(t *testing.T) {+ repo := &contactHandlerFakeRepo{countResult: 200}+ app := newContactHandlerTestAppWithEntitlements(repo, false, entities.SubscriptionNameFree)++ body := `[{"name":"Alice","phone_numbers":["+18005550199"]}]`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Len(t, stored, 1)+}++func TestContactHandler_Store_ValidationError_ReturnsUnprocessableEntity(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ body := `[{"name":"","phone_numbers":[]}]`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Empty(t, stored, "no contact should be stored on validation failure")+}++func TestContactHandler_Store_MalformedJSON_ReturnsBadRequest(t *testing.T) {+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString("{not json"))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusBadRequest, resp.StatusCode)+}++func buildContactCSVUpload(t *testing.T, filename string, contentType string, body string) (*bytes.Buffer, string) {+ t.Helper()+ var buf bytes.Buffer+ writer := multipart.NewWriter(&buf)++ header := make(textproto.MIMEHeader)+ header.Set("Content-Disposition", fmt.Sprintf(`form-data; name="document"; filename="%s"`, filename))+ header.Set("Content-Type", contentType)+ part, err := writer.CreatePart(header)+ require.NoError(t, err)+ _, err = part.Write([]byte(body))+ require.NoError(t, err)+ require.NoError(t, writer.Close())+ return &buf, writer.FormDataContentType()+}++func TestContactHandler_Upload_CSVSuccess(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ csv := "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199\nBob,,+18005550100\n"+ body, contentType := buildContactCSVUpload(t, "contacts.csv", "text/csv", csv)++ req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)+ req.Header.Set("Content-Type", contentType)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Len(t, stored, 1)+ require.Len(t, stored[0], 2)+ assert.Equal(t, "Alice", stored[0][0].Name)+ assert.Equal(t, "Bob", stored[0][1].Name)+ for _, c := range stored[0] {+ assert.Equal(t, contactHandlerTestUserID, c.UserID)+ }+}++func TestContactHandler_Upload_RejectsBatchExceedingContactLimit(t *testing.T) {+ repo := &contactHandlerFakeRepo{countResult: 199}+ app := newContactHandlerTestAppWithEntitlements(repo, true, entities.SubscriptionNameFree)++ csv := "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199\nBob,,+18005550100\n"+ body, contentType := buildContactCSVUpload(t, "contacts.csv", "text/csv", csv)+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)+ req.Header.Set("Content-Type", contentType)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusPaymentRequired, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ assert.Empty(t, stored)+}++func TestContactHandler_Upload_NonCSVFile_ReturnsUnprocessableEntity(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ body, contentType := buildContactCSVUpload(t, "contacts.txt", "text/plain", "junk")+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)+ req.Header.Set("Content-Type", contentType)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)++ stored, _, _, _ := repo.snapshot()+ require.Empty(t, stored)+}++func TestContactHandler_Upload_MissingDocument_ReturnsBadRequest(t *testing.T) {+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ // multipart body without the "document" field.+ var buf bytes.Buffer+ writer := multipart.NewWriter(&buf)+ require.NoError(t, writer.WriteField("other", "value"))+ require.NoError(t, writer.Close())++ req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", &buf)+ req.Header.Set("Content-Type", writer.FormDataContentType())++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusBadRequest, resp.StatusCode)+}++func TestContactHandler_Update_Success(t *testing.T) {+ contactID := uuid.New()+ repo := &contactHandlerFakeRepo{+ loadResult: &entities.Contact{+ ID: contactID,+ UserID: contactHandlerTestUserID,+ Name: "Old Name",+ PhoneNumbers: pq.StringArray{"+18005550100"},+ },+ }+ app := newContactHandlerTestApp(repo)++ body := `{"name":"New Name","phone_numbers":["+18005550199"],"emails":["[email protected]"]}`+ req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)++ _, updated, _, _ := repo.snapshot()+ require.Len(t, updated, 1)+ assert.Equal(t, "New Name", updated[0].Name)+ assert.Equal(t, contactID, updated[0].ID)+ assert.Equal(t, contactHandlerTestUserID, updated[0].UserID)+ assert.Equal(t, pq.StringArray{"+18005550199"}, updated[0].PhoneNumbers)++ // The repo Load call must have been user-scoped.+ require.Len(t, repo.loadCalls, 1)+ assert.Equal(t, contactHandlerTestUserID, repo.loadCalls[0].userID)+ assert.Equal(t, contactID, repo.loadCalls[0].id)+}++func TestContactHandler_Update_NotFound_ReturnsNotFound(t *testing.T) {+ contactID := uuid.New()+ repo := &contactHandlerFakeRepo{+ loadErr: stacktrace.PropagateWithCodef(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found"),+ }+ app := newContactHandlerTestApp(repo)++ body := `{"name":"New Name","phone_numbers":["+18005550199"]}`+ req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusNotFound, resp.StatusCode)++ payload := decodeContactHandlerPayload(t, resp)+ assert.Contains(t, payload.Message, contactID.String())++ _, updated, _, _ := repo.snapshot()+ assert.Empty(t, updated)+}++func TestContactHandler_Update_InvalidID_ReturnsUnprocessableEntity(t *testing.T) {+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ body := `{"name":"Alice","phone_numbers":["+18005550199"]}`+ req := httptest.NewRequest(http.MethodPut, "/v1/contacts/not-a-uuid", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)+}++func TestContactHandler_Update_ValidationError_ReturnsUnprocessableEntity(t *testing.T) {+ contactID := uuid.New()+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ body := `{"name":"","phone_numbers":[]}`+ req := httptest.NewRequest(http.MethodPut, "/v1/contacts/"+contactID.String(), bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)+}++func TestContactHandler_Delete_Success(t *testing.T) {+ contactID := uuid.New()+ repo := &contactHandlerFakeRepo{+ loadResult: &entities.Contact{+ ID: contactID,+ UserID: contactHandlerTestUserID,+ Name: "Alice",+ },+ }+ app := newContactHandlerTestApp(repo)++ req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/"+contactID.String(), nil)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusNoContent, resp.StatusCode)++ _, _, deleted, _ := repo.snapshot()+ require.Len(t, deleted, 1)+ assert.Equal(t, contactHandlerTestUserID, deleted[0].userID)+ assert.Equal(t, contactID, deleted[0].id)+}++func TestContactHandler_Delete_NotFound_ReturnsNotFound(t *testing.T) {+ contactID := uuid.New()+ repo := &contactHandlerFakeRepo{+ loadErr: stacktrace.PropagateWithCodef(gorm.ErrRecordNotFound, repositories.ErrCodeNotFound, "not found"),+ }+ app := newContactHandlerTestApp(repo)++ req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/"+contactID.String(), nil)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusNotFound, resp.StatusCode)++ // Ensure we did not delete another user's contact silently.+ _, _, deleted, _ := repo.snapshot()+ assert.Empty(t, deleted)+}++func TestContactHandler_Delete_InvalidID_ReturnsUnprocessableEntity(t *testing.T) {+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ req := httptest.NewRequest(http.MethodDelete, "/v1/contacts/not-a-uuid", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)+}++func TestContactHandler_Index_ConvertsQueryAndScopesToUser(t *testing.T) {+ repo := &contactHandlerFakeRepo{+ indexResult: []entities.Contact{+ {ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},+ },+ }+ app := newContactHandlerTestApp(repo)++ values := url.Values{}+ values.Set("skip", "5")+ values.Set("limit", "25")+ values.Set("query", "ali")+ values.Set("sort_by", "name")+ values.Set("sort_descending", "true")+ req := httptest.NewRequest(http.MethodGet, "/v1/contacts?"+values.Encode(), nil)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)++ _, _, _, indexParams := repo.snapshot()+ require.Len(t, indexParams, 1)+ assert.Equal(t, 5, indexParams[0].Skip)+ assert.Equal(t, 25, indexParams[0].Limit)+ assert.Equal(t, "ali", indexParams[0].Query)+ assert.Equal(t, "name", indexParams[0].SortBy)+ assert.True(t, indexParams[0].SortDescending)++ payload := decodeContactHandlerPayload(t, resp)+ assert.Equal(t, "success", payload.Status)+ assert.Contains(t, payload.Message, "1")+}++func TestContactHandler_Index_ReturnsServerTotalIndependentOfPageLength(t *testing.T) {+ repo := &contactHandlerFakeRepo{+ indexResult: []entities.Contact{+ {ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},+ {ID: uuid.New(), UserID: contactHandlerTestUserID, Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},+ },+ countResult: 57,+ }+ app := newContactHandlerTestApp(repo)++ values := url.Values{}+ values.Set("skip", "5")+ values.Set("limit", "25")+ values.Set("query", "ali")+ req := httptest.NewRequest(http.MethodGet, "/v1/contacts?"+values.Encode(), nil)++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)++ payload := decodeContactHandlerPayload(t, resp)+ assert.Equal(t, "success", payload.Status)+ // total must be the server count, not the length of the returned page.+ assert.Equal(t, int64(57), payload.Total)++ var data []entities.Contact+ require.NoError(t, json.Unmarshal(payload.Data, &data))+ assert.Len(t, data, 2)++ // Count must run with the exact same filter/pagination params as Index.+ require.Len(t, repo.indexParams, 1)+ require.Len(t, repo.countParams, 1)+ assert.Equal(t, repo.indexParams[0], repo.countParams[0])+ assert.Equal(t, 5, repo.countParams[0].Skip)+ assert.Equal(t, 25, repo.countParams[0].Limit)+ assert.Equal(t, "ali", repo.countParams[0].Query)+}++func TestContactHandler_Index_CountErrorReturnsInternalServerError(t *testing.T) {+ repo := &contactHandlerFakeRepo{countErr: assert.AnError}+ app := newContactHandlerTestApp(repo)++ req := httptest.NewRequest(http.MethodGet, "/v1/contacts", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusInternalServerError, resp.StatusCode)+}++func TestContactHandler_Index_DefaultsAppliedWhenParamsMissing(t *testing.T) {+ repo := &contactHandlerFakeRepo{}+ app := newContactHandlerTestApp(repo)++ req := httptest.NewRequest(http.MethodGet, "/v1/contacts", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)++ _, _, _, indexParams := repo.snapshot()+ require.Len(t, indexParams, 1)+ assert.Equal(t, 0, indexParams[0].Skip)+ assert.Equal(t, 20, indexParams[0].Limit)+ assert.Equal(t, "", indexParams[0].Query)+}++func TestContactHandler_Index_InvalidLimit_ReturnsUnprocessableEntity(t *testing.T) {+ app := newContactHandlerTestApp(&contactHandlerFakeRepo{})++ req := httptest.NewRequest(http.MethodGet, "/v1/contacts?limit=notanumber", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)+}++// TestContactService_WiresIntoMessageThreadService is a compile-time guard that+// pins the DI wiring change: ContactService must satisfy the contactMapProvider+// interface consumed by MessageThreadService, so container.MessageThreadService()+// can be constructed with container.ContactService() instead of nil.+func TestContactService_WiresIntoMessageThreadService(t *testing.T) {+ logger := &messageThreadHandlerNoopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ contactCache, err := ristretto.NewCache[string, services.ContactCacheEntry](&ristretto.Config[string, services.ContactCacheEntry]{+ MaxCost: 100, NumCounters: 1_000, BufferItems: 64,+ })+ require.NoError(t, err)+ t.Cleanup(contactCache.Close)+ contactService := services.NewContactService(logger, tracer, &contactHandlerFakeRepo{}, contactCache)++ // If this compiles and runs, the ContactService satisfies the+ // contactMapProvider interface expected by NewMessageThreadService.+ threadService := services.NewMessageThreadService(logger, tracer, nil, nil, nil, contactService)+ require.NotNil(t, threadService)+}diff --git a/api/pkg/handlers/handler.go b/api/pkg/handlers/handler.goindex 070e2db7..1f655b44 100644--- a/api/pkg/handlers/handler.go+++ b/api/pkg/handlers/handler.go@@ -97,6 +97,15 @@ func (h *handler) responseOK(c fiber.Ctx, message string, data interface{}) erro})}+func (h *handler) responseOKWithTotal(c fiber.Ctx, message string, data interface{}, total int64) error {+ return c.Status(fiber.StatusOK).JSON(fiber.Map{+ "status": "success",+ "message": message,+ "data": data,+ "total": total,+ })+}+func (h *handler) responseCreated(c fiber.Ctx, message string, data interface{}) error {return c.Status(fiber.StatusCreated).JSON(fiber.Map{"status": "success",diff --git a/api/pkg/handlers/message_thread_handler.go b/api/pkg/handlers/message_thread_handler.goindex a931302d..72e0b543 100644--- a/api/pkg/handlers/message_thread_handler.go+++ b/api/pkg/handlers/message_thread_handler.go@@ -57,6 +57,7 @@ func (h *MessageThreadHandler) RegisterRoutes(router fiber.Router, middlewares .// @Param skip query int false "number of messages to skip" minimum(0)// @Param query query string false "filter message threads containing query"// @Param limit query int false "number of messages to return" minimum(1) maximum(20)+// @Param contacts query bool false "include matching contact details"// @Success 200 {object} responses.MessageThreadsResponse// @Failure 400 {object} responses.BadRequest// @Failure 401 {object} responses.Unauthorizeddiff --git a/api/pkg/handlers/message_thread_handler_contacts_test.go b/api/pkg/handlers/message_thread_handler_contacts_test.gonew file mode 100644index 00000000..f6681fbd--- /dev/null+++ b/api/pkg/handlers/message_thread_handler_contacts_test.go@@ -0,0 +1,75 @@+package handlers++import (+ "context"+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/middlewares"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/httpsms/pkg/validators"+ "github.com/gofiber/fiber/v3"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type messageThreadHandlerIndexRepositoryStub struct {+ repositories.MessageThreadRepository+ threads []entities.MessageThread+}++func (stub *messageThreadHandlerIndexRepositoryStub) Index(context.Context, entities.UserID, string, bool, repositories.IndexParams) (*[]entities.MessageThread, error) {+ threads := make([]entities.MessageThread, len(stub.threads))+ copy(threads, stub.threads)+ return &threads, nil+}++type messageThreadHandlerContactProviderStub struct {+ contacts map[string]*entities.Contact+ calls int+}++func (stub *messageThreadHandlerContactProviderStub) GetContactMap(context.Context, entities.UserID, []string) (map[string]*entities.Contact, error) {+ stub.calls+++ return stub.contacts, nil+}++func TestMessageThreadHandlerIndex_ParsesContactsQuery(t *testing.T) {+ contact := &entities.Contact{ID: uuid.New(), Name: "Alice", PhoneNumbers: []string{"+18005550100"}}+ repository := &messageThreadHandlerIndexRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550100"}}}+ provider := &messageThreadHandlerContactProviderStub{contacts: map[string]*entities.Contact{"+18005550100": contact}}+ logger := &messageThreadHandlerNoopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ service := services.NewMessageThreadService(logger, tracer, repository, nil, nil, provider)+ handler := NewMessageThreadHandler(logger, tracer, validators.NewMessageThreadHandlerValidator(logger, tracer), service)++ app := fiber.New()+ app.Use(func(c fiber.Ctx) error {+ c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: entities.UserID("user-id"), Email: "[email protected]"})+ return c.Next()+ })+ handler.RegisterRoutes(app)++ req := httptest.NewRequest(http.MethodGet, "/v1/message-threads?owner=%2B18005550199&contacts=true", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})++ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)+ assert.Equal(t, 1, provider.calls)++ var payload struct {+ Data []entities.MessageThread `json:"data"`+ }+ require.NoError(t, json.NewDecoder(resp.Body).Decode(&payload))+ require.Len(t, payload.Data, 1)+ require.NotNil(t, payload.Data[0].ContactDetails)+ assert.Equal(t, contact.ID, payload.Data[0].ContactDetails.ID)+ assert.Equal(t, "Alice", payload.Data[0].ContactDetails.Name)+}diff --git a/api/pkg/handlers/message_thread_handler_test.go b/api/pkg/handlers/message_thread_handler_test.goindex fefb8189..56dfa0c7 100644--- a/api/pkg/handlers/message_thread_handler_test.go+++ b/api/pkg/handlers/message_thread_handler_test.go@@ -64,7 +64,7 @@ func (stub *messageThreadHandlerRepositoryStub) DeleteAllForUser(context.Contextfunc TestMessageThreadHandlerUpdate_ReturnsNotFoundWhenThreadIsMissing(t *testing.T) {logger := &messageThreadHandlerNoopLogger{}tracer := telemetry.NewOtelLogger("test", logger)- service := services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil)+ service := services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil, nil)handler := NewMessageThreadHandler(logger, tracer, validators.NewMessageThreadHandlerValidator(logger, tracer), service)app := fiber.New()diff --git a/api/pkg/listeners/contact_listener.go b/api/pkg/listeners/contact_listener.gonew file mode 100644index 00000000..c2b7d4d9--- /dev/null+++ b/api/pkg/listeners/contact_listener.go@@ -0,0 +1,57 @@+package listeners++import (+ "context"+ "fmt"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ cloudevents "github.com/cloudevents/sdk-go/v2"+)++// ContactDeletionService removes contacts belonging to a deleted user.+type ContactDeletionService interface {+ DeleteAllForUser(ctx context.Context, userID entities.UserID) error+}++// ContactListener handles contact-related cloud events.+type ContactListener struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ service ContactDeletionService+}++// NewContactListener creates a new ContactListener.+func NewContactListener(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ service ContactDeletionService,+) (l *ContactListener, routes map[string]events.EventListener) {+ l = &ContactListener{+ logger: logger.WithService(fmt.Sprintf("%T", l)),+ tracer: tracer,+ service: service,+ }++ return l, map[string]events.EventListener{+ events.UserAccountDeleted: l.onUserAccountDeleted,+ }+}++func (listener *ContactListener) onUserAccountDeleted(ctx context.Context, event cloudevents.Event) error {+ ctx, span := listener.tracer.Start(ctx)+ defer span.End()++ var payload events.UserAccountDeletedPayload+ if err := event.DataAs(&payload); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot decode [%s] into [%T]", event.Data(), payload))+ }++ if err := listener.service.DeleteAllForUser(ctx, payload.UserID); err != nil {+ return listener.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete [entities.Contact] for user [%s] on [%s] event with ID [%s]", payload.UserID, event.Type(), event.ID()))+ }++ return nil+}diff --git a/api/pkg/listeners/contact_listener_test.go b/api/pkg/listeners/contact_listener_test.gonew file mode 100644index 00000000..2296f399--- /dev/null+++ b/api/pkg/listeners/contact_listener_test.go@@ -0,0 +1,70 @@+package listeners++import (+ "context"+ "errors"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ cloudevents "github.com/cloudevents/sdk-go/v2"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type contactDeletionServiceStub struct {+ userIDs []entities.UserID+ err error+}++func (service *contactDeletionServiceStub) DeleteAllForUser(_ context.Context, userID entities.UserID) error {+ service.userIDs = append(service.userIDs, userID)+ return service.err+}++func TestContactListenerDeletesContactsForDeletedUser(t *testing.T) {+ service := &contactDeletionServiceStub{}+ routes := newContactListenerRoutes(t, service)+ event := deletedUserContactEvent(t, entities.UserID("user-id"))++ err := routes[events.UserAccountDeleted](context.Background(), event)++ require.NoError(t, err)+ assert.Equal(t, []entities.UserID{"user-id"}, service.userIDs)+}++func TestContactListenerWrapsDeleteError(t *testing.T) {+ service := &contactDeletionServiceStub{err: errors.New("delete contacts boom")}+ routes := newContactListenerRoutes(t, service)+ event := deletedUserContactEvent(t, entities.UserID("user-id"))++ err := routes[events.UserAccountDeleted](context.Background(), event)++ require.Error(t, err)+ assert.Contains(t, err.Error(), "delete contacts boom")+}++func newContactListenerRoutes(t *testing.T, service *contactDeletionServiceStub) map[string]events.EventListener {+ t.Helper()++ logger := &noopListenerLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ _, routes := NewContactListener(logger, tracer, service)+ require.Contains(t, routes, events.UserAccountDeleted)+ return routes+}++func deletedUserContactEvent(t *testing.T, userID entities.UserID) cloudevents.Event {+ t.Helper()++ event := cloudevents.NewEvent()+ event.SetID(uuid.NewString())+ event.SetSource("/v1/users")+ event.SetType(events.UserAccountDeleted)+ require.NoError(t, event.SetData(cloudevents.ApplicationJSON, events.UserAccountDeletedPayload{+ UserID: userID,+ }))+ return event+}diff --git a/api/pkg/listeners/message_thread_listener_test.go b/api/pkg/listeners/message_thread_listener_test.goindex 39a444cc..f0410dfa 100644--- a/api/pkg/listeners/message_thread_listener_test.go+++ b/api/pkg/listeners/message_thread_listener_test.go@@ -66,7 +66,7 @@ func newMessageThreadListenerForTest() (*listenerMessageThreadRepository, map[strepository := &listenerMessageThreadRepository{}logger := &noopListenerLogger{}tracer := telemetry.NewOtelLogger("test", logger)- service := services.NewMessageThreadService(logger, tracer, repository, nil, nil)+ service := services.NewMessageThreadService(logger, tracer, repository, nil, nil, nil)_, routes := NewMessageThreadListener(logger, tracer, service)return repository, routes}diff --git a/api/pkg/repositories/contact_repository.go b/api/pkg/repositories/contact_repository.gonew file mode 100644index 00000000..87c89a6a--- /dev/null+++ b/api/pkg/repositories/contact_repository.go@@ -0,0 +1,37 @@+package repositories++import (+ "context"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+)++// ContactRepository loads and persists an entities.Contact.+type ContactRepository interface {+ // Store one or many new entities.Contact.+ Store(ctx context.Context, contacts []*entities.Contact) error++ // Update an existing entities.Contact.+ Update(ctx context.Context, contact *entities.Contact) error++ // Load a contact by ID for a user.+ Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)++ // Index contacts for a user with optional search.+ Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)++ // Count returns the number of contacts for a user matching the same+ // name/emails/phone_numbers filter as Index, ignoring pagination.+ Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error)++ // FetchByPhoneNumbers returns contacts containing at least one requested+ // phone number, ordered by updated_at ascending.+ FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error)++ // Delete a contact by ID for a user.+ Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error++ // DeleteAllForUser deletes all contacts for a user.+ DeleteAllForUser(ctx context.Context, userID entities.UserID) error+}diff --git a/api/pkg/repositories/gorm_contact_repository.go b/api/pkg/repositories/gorm_contact_repository.gonew file mode 100644index 00000000..2ecee4de--- /dev/null+++ b/api/pkg/repositories/gorm_contact_repository.go@@ -0,0 +1,187 @@+package repositories++import (+ "context"+ "errors"+ "fmt"+ "strings"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "gorm.io/gorm"+)++// gormContactRepository is responsible for persisting entities.Contact.+type gormContactRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ db *gorm.DB+}++// NewGormContactRepository creates the GORM version of the ContactRepository.+func NewGormContactRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ db *gorm.DB,+) ContactRepository {+ return &gormContactRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &gormContactRepository{})),+ tracer: tracer,+ db: db,+ }+}++func (repository *gormContactRepository) Store(ctx context.Context, contacts []*entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if len(contacts) == 0 {+ return nil+ }++ if err := repository.db.WithContext(ctx).Create(&contacts).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts", len(contacts)))+ }++ return nil+}++func (repository *gormContactRepository) Update(ctx context.Context, contact *entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.db.WithContext(ctx).Save(contact).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact with ID [%s]", contact.ID))+ }++ return nil+}++func (repository *gormContactRepository) Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ contact := new(entities.Contact)+ err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Where("id = ?", contactID).+ First(contact).Error+ if errors.Is(err, gorm.ErrRecordNotFound) {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, ErrCodeNotFound, "contact with ID [%s] for user [%s] does not exist", contactID, userID))+ }++ if err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot load contact with ID [%s] for user [%s]", contactID, userID))+ }++ return contact, nil+}++// scopedContactQuery builds the shared query that scopes contacts to a user and+// applies the optional name/emails/phone_numbers search filter. Index and Count+// both build on it so their filters can never drift apart. It sets the model so+// callers can chain Find or Count without repeating the table.+func (repository *gormContactRepository) scopedContactQuery(ctx context.Context, userID entities.UserID, query string) *gorm.DB {+ scoped := repository.db.WithContext(ctx).Model(&entities.Contact{}).Where("user_id = ?", userID)+ if len(query) > 0 {+ escaped := strings.NewReplacer(`%`, `\%`, `_`, `\_`).Replace(query)+ queryPattern := "%" + escaped + "%"+ scoped = scoped.Where(+ repository.db.WithContext(ctx).Where("name ILIKE ?", queryPattern).+ Or("array_to_string(emails, ',') ILIKE ?", queryPattern).+ Or("array_to_string(phone_numbers, ',') ILIKE ?", queryPattern),+ )+ }+ return scoped+}++func (repository *gormContactRepository) Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ contacts := new([]entities.Contact)+ if err := repository.scopedContactQuery(ctx, userID, params.Query).+ Order(repository.contactOrder(params)).+ Limit(params.Limit).+ Offset(params.Skip).+ Find(contacts).Error; err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s] with params [%+#v]", userID, params))+ }++ return contacts, nil+}++func (repository *gormContactRepository) contactOrder(params IndexParams) string {+ if params.SortBy == "" {+ return "updated_at DESC, id DESC"+ }++ sortBy := "updated_at"+ if params.SortBy == "name" {+ sortBy = "name"+ }++ direction := "ASC"+ if params.SortDescending {+ direction = "DESC"+ }++ return fmt.Sprintf("%s %s, id %s", sortBy, direction, direction)+}++func (repository *gormContactRepository) Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ var count int64+ if err := repository.scopedContactQuery(ctx, userID, params.Query).Count(&count).Error; err != nil {+ return 0, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot count contacts for user [%s] with query [%s]", userID, params.Query))+ }++ return count, nil+}++func (repository *gormContactRepository) FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ contacts := new([]entities.Contact)+ if err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Where("phone_numbers && ?", pq.Array(phoneNumbers)).+ Order("updated_at ASC, id ASC").+ Find(contacts).Error; err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts for user [%s] by phone numbers [%v]", userID, phoneNumbers))+ }++ return contacts, nil+}++func (repository *gormContactRepository) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Where("id = ?", contactID).+ Delete(&entities.Contact{}).Error+ if err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact with ID [%s] for user [%s]", contactID, userID))+ }++ return nil+}++func (repository *gormContactRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.db.WithContext(ctx).Where("user_id = ?", userID).Delete(&entities.Contact{}).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))+ }++ return nil+}diff --git a/api/pkg/repositories/gorm_contact_repository_test.go b/api/pkg/repositories/gorm_contact_repository_test.gonew file mode 100644index 00000000..16616102--- /dev/null+++ b/api/pkg/repositories/gorm_contact_repository_test.go@@ -0,0 +1,365 @@+package repositories++import (+ "context"+ "database/sql"+ "database/sql/driver"+ "io"+ "regexp"+ "strings"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/postgres"+ "gorm.io/gorm"+)++func normalizeContactSQL(query string) string {+ return strings.Join(strings.Fields(query), " ")+}++type contactTestConnPool struct {+ messageThreadTestConnPool+}++func (pool *contactTestConnPool) QueryContext(_ context.Context, query string, args ...any) (*sql.Rows, error) {+ pool.statements = append(pool.statements, messageThreadTestStatement{+ query: query,+ args: append([]any(nil), args...),+ })++ db := sql.OpenDB(contactTestRowsConnector{})+ return db.QueryContext(context.Background(), "SELECT 1")+}++func (pool *contactTestConnPool) BeginTx(context.Context, *sql.TxOptions) (gorm.ConnPool, error) {+ return pool, nil+}++type contactTestRowsConnector struct{}++func (contactTestRowsConnector) Connect(context.Context) (driver.Conn, error) {+ return contactTestRowsConn{}, nil+}++func (contactTestRowsConnector) Driver() driver.Driver {+ return contactTestRowsDriver{}+}++type contactTestRowsDriver struct{}++func (contactTestRowsDriver) Open(string) (driver.Conn, error) {+ return contactTestRowsConn{}, nil+}++type contactTestRowsConn struct{}++func (contactTestRowsConn) Prepare(string) (driver.Stmt, error) {+ return nil, assert.AnError+}++func (contactTestRowsConn) Close() error {+ return nil+}++func (contactTestRowsConn) Begin() (driver.Tx, error) {+ return nil, assert.AnError+}++func (contactTestRowsConn) QueryContext(context.Context, string, []driver.NamedValue) (driver.Rows, error) {+ return contactTestRows{}, nil+}++type contactTestRows struct{}++func (contactTestRows) Columns() []string {+ return []string{"id", "user_id", "name", "emails", "phone_numbers", "properties", "created_at", "updated_at"}+}++func (contactTestRows) Close() error {+ return nil+}++func (contactTestRows) Next([]driver.Value) error {+ return io.EOF+}++func lastContactStatement(t *testing.T, pool *contactTestConnPool) messageThreadTestStatement {+ t.Helper()+ require.NotEmpty(t, pool.statements)++ statement := pool.statements[len(pool.statements)-1]+ statement.query = normalizeContactSQL(statement.query)+ return statement+}++func newContactTestRepo(t *testing.T) (ContactRepository, *contactTestConnPool) {+ t.Helper()++ pool := &contactTestConnPool{}+ db, err := gorm.Open(+ postgres.New(postgres.Config{+ Conn: pool,+ WithoutReturning: true,+ }),+ &gorm.Config{+ DisableAutomaticPing: true,+ NowFunc: func() time.Time {+ return time.Date(2026, 7, 19, 18, 0, 0, 0, time.UTC)+ },+ },+ )+ require.NoError(t, err)++ logger := &messageThreadTestLogger{}+ return NewGormContactRepository(logger, telemetry.NewOtelLogger("test", logger), db), pool+}++func TestGormContactRepository_Store_BatchInsertsContacts(t *testing.T) {+ repository, recorder := newContactTestRepo(t)+ firstID := uuid.MustParse("11111111-1111-1111-1111-111111111111")+ secondID := uuid.MustParse("22222222-2222-2222-2222-222222222222")++ err := repository.Store(context.Background(), []*entities.Contact{+ {+ ID: firstID,+ UserID: entities.UserID("user-1"),+ Name: "Alice",+ Emails: pq.StringArray{"[email protected]"},+ PhoneNumbers: pq.StringArray{"+18005550199"},+ Properties: entities.ContactProperties{"source": "phone"},+ },+ {+ ID: secondID,+ UserID: entities.UserID("user-1"),+ Name: "Bob",+ Emails: pq.StringArray{"[email protected]"},+ PhoneNumbers: pq.StringArray{"+18005550200"},+ Properties: entities.ContactProperties{"source": "import"},+ },+ })++ require.NoError(t, err)+ require.Len(t, recorder.statements, 1)+ statement := lastContactStatement(t, recorder)+ assert.True(t, strings.HasPrefix(statement.query, `INSERT INTO "contacts"`))+ assert.Contains(t, statement.query, `("id","user_id","name","emails","phone_numbers","properties","created_at","updated_at")`)+ assert.Regexp(t, regexp.MustCompile(`VALUES \(\$1,\$2,\$3,\$4,\$5,\$6,\$7,\$8\),\(\$9,\$10,\$11,\$12,\$13,\$14,\$15,\$16\)`), statement.query)+ require.Len(t, statement.args, 16)+ assert.Equal(t, firstID, statement.args[0])+ assert.Equal(t, entities.UserID("user-1"), statement.args[1])+ assert.Equal(t, "Alice", statement.args[2])+ assert.Equal(t, pq.StringArray{"[email protected]"}, statement.args[3])+ assert.Equal(t, pq.StringArray{"+18005550199"}, statement.args[4])+ assert.Equal(t, entities.ContactProperties{"source": "phone"}, statement.args[5])+ assert.Equal(t, secondID, statement.args[8])+ assert.Equal(t, entities.UserID("user-1"), statement.args[9])+ assert.Equal(t, "Bob", statement.args[10])+ assert.Equal(t, pq.StringArray{"[email protected]"}, statement.args[11])+ assert.Equal(t, pq.StringArray{"+18005550200"}, statement.args[12])+ assert.Equal(t, entities.ContactProperties{"source": "import"}, statement.args[13])+}++func TestGormContactRepository_Update_SavesContact(t *testing.T) {+ repository, recorder := newContactTestRepo(t)+ contactID := uuid.MustParse("33333333-3333-3333-3333-333333333333")++ err := repository.Update(context.Background(), &entities.Contact{+ ID: contactID,+ UserID: entities.UserID("user-1"),+ Name: "Updated Alice",+ Emails: pq.StringArray{"[email protected]"},+ PhoneNumbers: pq.StringArray{"+18005550199"},+ Properties: entities.ContactProperties{"group": "friends"},+ })++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.True(t, strings.HasPrefix(statement.query, `UPDATE "contacts"`))+ assert.Contains(t, statement.query, `"user_id"=$1`)+ assert.Contains(t, statement.query, `"name"=$2`)+ assert.Contains(t, statement.query, `"emails"=$3`)+ assert.Contains(t, statement.query, `"phone_numbers"=$4`)+ assert.Contains(t, statement.query, `"properties"=$5`)+ assert.Contains(t, statement.query, `"created_at"=$6`)+ assert.Contains(t, statement.query, `"updated_at"=$7`)+ assert.Contains(t, statement.query, `WHERE "id" = $8`)+ require.Len(t, statement.args, 8)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, "Updated Alice", statement.args[1])+ assert.Equal(t, pq.StringArray{"[email protected]"}, statement.args[2])+ assert.Equal(t, pq.StringArray{"+18005550199"}, statement.args[3])+ assert.Equal(t, entities.ContactProperties{"group": "friends"}, statement.args[4])+ assert.Equal(t, contactID, statement.args[7])+}++func TestGormContactRepository_Load_ScopesByUserAndContactID(t *testing.T) {+ repository, recorder := newContactTestRepo(t)+ contactID := uuid.MustParse("44444444-4444-4444-4444-444444444444")++ _, err := repository.Load(context.Background(), entities.UserID("user-1"), contactID)++ require.Error(t, err)+ assert.Equal(t, ErrCodeNotFound, stacktrace.GetCode(err))+ statement := lastContactStatement(t, recorder)+ assert.True(t, strings.HasPrefix(statement.query, `SELECT * FROM "contacts"`))+ assert.Contains(t, statement.query, `WHERE user_id = $1 AND id = $2`)+ assert.Contains(t, statement.query, `ORDER BY "contacts"."id" LIMIT $3`)+ require.Len(t, statement.args, 3)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, contactID, statement.args[1])+ assert.Equal(t, 1, statement.args[2])+}++func TestGormContactRepository_Count_ReusesIndexFilterWithoutPagination(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ total, err := repository.Count(context.Background(), entities.UserID("user-1"), IndexParams{+ Query: "alice",+ // Limit/Skip must be ignored by Count.+ Limit: 20,+ Skip: 40,+ })++ require.NoError(t, err)+ assert.Equal(t, int64(0), total)++ statement := lastContactStatement(t, recorder)+ assert.True(t, strings.HasPrefix(statement.query, `SELECT count(*) FROM "contacts"`))+ // Count must apply the exact same user + name/emails/phone_numbers filter as Index.+ assert.Contains(t, statement.query, `WHERE user_id = $1 AND (name ILIKE $2 OR array_to_string(emails, ',') ILIKE $3 OR array_to_string(phone_numbers, ',') ILIKE $4)`)+ // Count must ignore pagination.+ assert.NotContains(t, statement.query, "LIMIT")+ assert.NotContains(t, statement.query, "OFFSET")+ require.Len(t, statement.args, 4)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, "%alice%", statement.args[1])+ assert.Equal(t, "%alice%", statement.args[2])+ assert.Equal(t, "%alice%", statement.args[3])+}++func TestGormContactRepository_Count_ScopesByUserWithoutQuery(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ _, err := repository.Count(context.Background(), entities.UserID("user-1"), IndexParams{})++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.Equal(t, `SELECT count(*) FROM "contacts" WHERE user_id = $1`, statement.query)+ require.Len(t, statement.args, 1)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+}++func TestGormContactRepository_Index_FiltersByUserAndQueryAcrossContactFields(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ _, err := repository.Index(context.Background(), entities.UserID("user-1"), IndexParams{+ Query: "alice",+ Limit: 20,+ Skip: 40,+ })++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.True(t, strings.HasPrefix(statement.query, `SELECT * FROM "contacts"`))+ assert.Contains(t, statement.query, `WHERE user_id = $1 AND (name ILIKE $2 OR array_to_string(emails, ',') ILIKE $3 OR array_to_string(phone_numbers, ',') ILIKE $4)`)+ assert.Contains(t, statement.query, `ORDER BY updated_at DESC, id DESC LIMIT $5 OFFSET $6`)+ require.Len(t, statement.args, 6)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, "%alice%", statement.args[1])+ assert.Equal(t, "%alice%", statement.args[2])+ assert.Equal(t, "%alice%", statement.args[3])+ assert.Equal(t, 20, statement.args[4])+ assert.Equal(t, 40, statement.args[5])+}++func TestGormContactRepository_Index_OrdersByRequestedFieldAndDirection(t *testing.T) {+ tests := []struct {+ name string+ params IndexParams+ expectedOrderBy string+ }{+ {+ name: "name ascending",+ params: IndexParams{SortBy: "name"},+ expectedOrderBy: "ORDER BY name ASC, id ASC",+ },+ {+ name: "name descending",+ params: IndexParams{SortBy: "name", SortDescending: true},+ expectedOrderBy: "ORDER BY name DESC, id DESC",+ },+ {+ name: "updated descending",+ params: IndexParams{SortBy: "updated_at", SortDescending: true},+ expectedOrderBy: "ORDER BY updated_at DESC, id DESC",+ },+ {+ name: "default",+ params: IndexParams{},+ expectedOrderBy: "ORDER BY updated_at DESC, id DESC",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ _, err := repository.Index(context.Background(), entities.UserID("user-1"), tt.params)++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.Contains(t, statement.query, tt.expectedOrderBy)+ })+ }+}++func TestGormContactRepository_FetchByPhoneNumbers_ScopesByUserAndRequestedNumbers(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ _, err := repository.FetchByPhoneNumbers(+ context.Background(),+ entities.UserID("user-1"),+ []string{"+18005550199", "+18005550100"},+ )++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.Equal(t, `SELECT * FROM "contacts" WHERE user_id = $1 AND phone_numbers && $2 ORDER BY updated_at ASC, id ASC`, statement.query)+ require.Len(t, statement.args, 2)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, &pq.StringArray{"+18005550199", "+18005550100"}, statement.args[1])+}++func TestGormContactRepository_Delete_ScopesByUserAndContactID(t *testing.T) {+ repository, recorder := newContactTestRepo(t)+ contactID := uuid.MustParse("55555555-5555-5555-5555-555555555555")++ err := repository.Delete(context.Background(), entities.UserID("user-1"), contactID)++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.Equal(t, `DELETE FROM "contacts" WHERE user_id = $1 AND id = $2`, statement.query)+ require.Len(t, statement.args, 2)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+ assert.Equal(t, contactID, statement.args[1])+}++func TestGormContactRepository_DeleteAllForUser_ScopesByUserOnly(t *testing.T) {+ repository, recorder := newContactTestRepo(t)++ err := repository.DeleteAllForUser(context.Background(), entities.UserID("user-1"))++ require.NoError(t, err)+ statement := lastContactStatement(t, recorder)+ assert.Equal(t, `DELETE FROM "contacts" WHERE user_id = $1`, statement.query)+ require.Len(t, statement.args, 1)+ assert.Equal(t, entities.UserID("user-1"), statement.args[0])+}diff --git a/api/pkg/repositories/mongo_contact_repository.go b/api/pkg/repositories/mongo_contact_repository.gonew file mode 100644index 00000000..6cca028c--- /dev/null+++ b/api/pkg/repositories/mongo_contact_repository.go@@ -0,0 +1,239 @@+package repositories++import (+ "context"+ "fmt"+ "regexp"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "go.mongodb.org/mongo-driver/v2/bson"+ "go.mongodb.org/mongo-driver/v2/mongo"+ "go.mongodb.org/mongo-driver/v2/mongo/options"+)++// mongoContactRepository is responsible for persisting entities.Contact in MongoDB.+type mongoContactRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ collection *mongo.Collection+}++// NewMongoContactRepository creates the MongoDB version of the ContactRepository.+func NewMongoContactRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ db *mongo.Database,+) ContactRepository {+ return &mongoContactRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &mongoContactRepository{})),+ tracer: tracer,+ collection: db.Collection(collectionContacts),+ }+}++func (repository *mongoContactRepository) Store(ctx context.Context, contacts []*entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if len(contacts) == 0 {+ return nil+ }++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ documents := make([]any, len(contacts))+ for index, contact := range contacts {+ documents[index] = contact+ }++ session, err := repository.collection.Database().Client().StartSession()+ if err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot start transaction to store [%d] contacts", len(contacts)))+ }+ defer session.EndSession(ctx)++ _, err = session.WithTransaction(ctx, func(transactionCtx context.Context) (any, error) {+ return repository.collection.InsertMany(transactionCtx, documents)+ })+ if err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts", len(contacts)))+ }++ return nil+}++func (repository *mongoContactRepository) Update(ctx context.Context, contact *entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ filter := mongoContactIDFilter(contact.UserID, contact.ID)+ if _, err := repository.collection.ReplaceOne(ctx, filter, contact); err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact with ID [%s]", contact.ID))+ }++ return nil+}++func (repository *mongoContactRepository) Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ contact := new(entities.Contact)+ err := repository.collection.FindOne(ctx, mongoContactIDFilter(userID, contactID)).Decode(contact)+ if err == mongo.ErrNoDocuments {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, ErrCodeNotFound, "contact with ID [%s] for user [%s] does not exist", contactID, userID))+ }+ if err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot load contact with ID [%s] for user [%s]", contactID, userID))+ }++ return contact, nil+}++func (repository *mongoContactRepository) Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ findOptions := options.Find().+ SetSort(mongoContactSort(params)).+ SetSkip(int64(params.Skip)).+ SetLimit(int64(params.Limit))+ cursor, err := repository.collection.Find(ctx, mongoContactFilter(userID, params.Query), findOptions)+ if err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s] with params [%+#v]", userID, params))+ }+ defer cursor.Close(ctx)++ contacts := make([]entities.Contact, 0)+ if err = cursor.All(ctx, &contacts); err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot decode contacts for user [%s]", userID))+ }++ return &contacts, nil+}++func (repository *mongoContactRepository) Count(ctx context.Context, userID entities.UserID, params IndexParams) (int64, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ count, err := repository.collection.CountDocuments(ctx, mongoContactFilter(userID, params.Query))+ if err != nil {+ return 0, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot count contacts for user [%s] with query [%s]", userID, params.Query))+ }++ return count, nil+}++func (repository *mongoContactRepository) FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ findOptions := options.Find().SetSort(bson.D{+ {Key: "updated_at", Value: 1},+ {Key: "_id", Value: 1},+ })+ cursor, err := repository.collection.Find(ctx, mongoContactPhoneNumbersFilter(userID, phoneNumbers), findOptions)+ if err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts for user [%s] by phone numbers [%v]", userID, phoneNumbers))+ }+ defer cursor.Close(ctx)++ contacts := make([]entities.Contact, 0)+ if err = cursor.All(ctx, &contacts); err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot decode contacts for user [%s] by phone numbers", userID))+ }++ return &contacts, nil+}++func (repository *mongoContactRepository) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ if _, err := repository.collection.DeleteOne(ctx, mongoContactIDFilter(userID, contactID)); err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact with ID [%s] for user [%s]", contactID, userID))+ }++ return nil+}++func (repository *mongoContactRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ ctx, cancel := context.WithTimeout(ctx, dbOperationDuration)+ defer cancel()++ if _, err := repository.collection.DeleteMany(ctx, bson.D{{Key: "user_id", Value: string(userID)}}); err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))+ }++ return nil+}++func mongoContactFilter(userID entities.UserID, query string) bson.D {+ filter := bson.D{{Key: "user_id", Value: string(userID)}}+ if query == "" {+ return filter+ }++ expression := bson.Regex{Pattern: regexp.QuoteMeta(query), Options: "i"}+ return append(filter, bson.E{Key: "$or", Value: bson.A{+ bson.D{{Key: "name", Value: expression}},+ bson.D{{Key: "emails", Value: expression}},+ bson.D{{Key: "phone_numbers", Value: expression}},+ }})+}++func mongoContactSort(params IndexParams) bson.D {+ sortBy := "updated_at"+ if params.SortBy == "name" {+ sortBy = "name"+ }++ direction := 1+ if params.SortBy == "" || params.SortDescending {+ direction = -1+ }++ return bson.D{+ {Key: sortBy, Value: direction},+ {Key: "_id", Value: direction},+ }+}++func mongoContactPhoneNumbersFilter(userID entities.UserID, phoneNumbers []string) bson.D {+ return bson.D{+ {Key: "user_id", Value: string(userID)},+ {Key: "phone_numbers", Value: bson.D{{Key: "$in", Value: phoneNumbers}}},+ }+}++func mongoContactIDFilter(userID entities.UserID, contactID uuid.UUID) bson.D {+ return bson.D{+ {Key: "user_id", Value: string(userID)},+ {Key: "_id", Value: contactID.String()},+ }+}diff --git a/api/pkg/repositories/mongo_contact_repository_test.go b/api/pkg/repositories/mongo_contact_repository_test.gonew file mode 100644index 00000000..4f6ba1c7--- /dev/null+++ b/api/pkg/repositories/mongo_contact_repository_test.go@@ -0,0 +1,124 @@+package repositories++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "go.mongodb.org/mongo-driver/v2/bson"+)++func TestMongoContactFilter_ScopesByUserAndSearchesContactFields(t *testing.T) {+ filter := mongoContactFilter(entities.UserID("user-1"), "Alice")++ assert.Equal(t, bson.D{+ {Key: "user_id", Value: "user-1"},+ {Key: "$or", Value: bson.A{+ bson.D{{Key: "name", Value: bson.Regex{Pattern: "Alice", Options: "i"}}},+ bson.D{{Key: "emails", Value: bson.Regex{Pattern: "Alice", Options: "i"}}},+ bson.D{{Key: "phone_numbers", Value: bson.Regex{Pattern: "Alice", Options: "i"}}},+ }},+ }, filter)+}++func TestMongoContactFilter_WithoutSearchOnlyScopesByUser(t *testing.T) {+ filter := mongoContactFilter(entities.UserID("user-1"), "")++ assert.Equal(t, bson.D{{Key: "user_id", Value: "user-1"}}, filter)+}++func TestMongoContactFilter_TreatsSearchAsLiteralText(t *testing.T) {+ filter := mongoContactFilter(entities.UserID("user-1"), "Alice.*")++ expectedExpression := bson.Regex{Pattern: `Alice\.\*`, Options: "i"}+ assert.Equal(t, bson.D{+ {Key: "user_id", Value: "user-1"},+ {Key: "$or", Value: bson.A{+ bson.D{{Key: "name", Value: expectedExpression}},+ bson.D{{Key: "emails", Value: expectedExpression}},+ bson.D{{Key: "phone_numbers", Value: expectedExpression}},+ }},+ }, filter)+}++func TestMongoContactSort_UsesStableRequestedOrdering(t *testing.T) {+ tests := []struct {+ name string+ params IndexParams+ expected bson.D+ }{+ {+ name: "default",+ params: IndexParams{},+ expected: bson.D{{Key: "updated_at", Value: -1}, {Key: "_id", Value: -1}},+ },+ {+ name: "name ascending",+ params: IndexParams{SortBy: "name"},+ expected: bson.D{{Key: "name", Value: 1}, {Key: "_id", Value: 1}},+ },+ {+ name: "name descending",+ params: IndexParams{SortBy: "name", SortDescending: true},+ expected: bson.D{{Key: "name", Value: -1}, {Key: "_id", Value: -1}},+ },+ {+ name: "updated ascending",+ params: IndexParams{SortBy: "updated_at"},+ expected: bson.D{{Key: "updated_at", Value: 1}, {Key: "_id", Value: 1}},+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ assert.Equal(t, tt.expected, mongoContactSort(tt.params))+ })+ }+}++func TestMongoContactPhoneNumbersFilter_ScopesByUserAndRequestedNumbers(t *testing.T) {+ filter := mongoContactPhoneNumbersFilter(+ entities.UserID("user-1"),+ []string{"+18005550199", "+18005550100"},+ )++ assert.Equal(t, bson.D{+ {Key: "user_id", Value: "user-1"},+ {Key: "phone_numbers", Value: bson.D{{Key: "$in", Value: []string{"+18005550199", "+18005550100"}}}},+ }, filter)+}++func TestMongoContactIDFilter_ScopesByUserAndContactID(t *testing.T) {+ contactID := uuid.MustParse("11111111-1111-1111-1111-111111111111")++ filter := mongoContactIDFilter(entities.UserID("user-1"), contactID)++ assert.Equal(t, bson.D{+ {Key: "user_id", Value: "user-1"},+ {Key: "_id", Value: contactID.String()},+ }, filter)+}++func TestContactMongoIndexModels_CoverListingAndPhoneLookup(t *testing.T) {+ indexes := contactMongoIndexModels()++ require.Len(t, indexes, 3)+ assert.Equal(t, bson.D{+ {Key: "user_id", Value: 1},+ {Key: "updated_at", Value: -1},+ {Key: "_id", Value: -1},+ }, indexes[0].Keys)+ assert.Equal(t, bson.D{+ {Key: "user_id", Value: 1},+ {Key: "name", Value: 1},+ {Key: "_id", Value: 1},+ }, indexes[1].Keys)+ assert.Equal(t, bson.D{+ {Key: "user_id", Value: 1},+ {Key: "phone_numbers", Value: 1},+ {Key: "updated_at", Value: 1},+ {Key: "_id", Value: 1},+ }, indexes[2].Keys)+}diff --git a/api/pkg/repositories/mongodb.go b/api/pkg/repositories/mongodb.goindex ebefc0f8..44f35bd4 100644--- a/api/pkg/repositories/mongodb.go+++ b/api/pkg/repositories/mongodb.go@@ -17,6 +17,7 @@ import (const (collectionHeartbeats = "heartbeats"collectionHeartbeatMonitors = "heartbeat_monitors"+ collectionContacts = "contacts")// uuidEncodeValue encodes uuid.UUID as a BSON string@@ -122,5 +123,32 @@ func createMongoIndexes(ctx context.Context, db *mongo.Database) error {return stacktrace.Propagatef(err, "cannot create indexes on heartbeat_monitors collection")}+ contactsCol := db.Collection(collectionContacts)+ _, err = contactsCol.Indexes().CreateMany(ctx, contactMongoIndexModels())+ if err != nil {+ return stacktrace.Propagatef(err, "cannot create indexes on contacts collection")+ }+return nil}++func contactMongoIndexModels() []mongo.IndexModel {+ return []mongo.IndexModel{+ {Keys: bson.D{+ {Key: "user_id", Value: 1},+ {Key: "updated_at", Value: -1},+ {Key: "_id", Value: -1},+ }},+ {Keys: bson.D{+ {Key: "user_id", Value: 1},+ {Key: "name", Value: 1},+ {Key: "_id", Value: 1},+ }},+ {Keys: bson.D{+ {Key: "user_id", Value: 1},+ {Key: "phone_numbers", Value: 1},+ {Key: "updated_at", Value: 1},+ {Key: "_id", Value: 1},+ }},+ }+}diff --git a/api/pkg/requests/contact_index.go b/api/pkg/requests/contact_index.gonew file mode 100644index 00000000..6940384a--- /dev/null+++ b/api/pkg/requests/contact_index.go@@ -0,0 +1,44 @@+package requests++import (+ "strings"++ "github.com/NdoleStudio/httpsms/pkg/repositories"+)++// ContactIndex lists contacts for a user.+type ContactIndex struct {+ request+ Skip string `json:"skip" query:"skip"`+ Query string `json:"query" query:"query"`+ SortBy string `json:"sort_by" query:"sort_by"`+ SortDescending bool `json:"sort_descending" query:"sort_descending"`+ Limit string `json:"limit" query:"limit"`+}++// Sanitize sets defaults for the list request.+func (input *ContactIndex) Sanitize() ContactIndex {+ input.Query = strings.TrimSpace(input.Query)+ input.SortBy = strings.TrimSpace(input.SortBy)+ input.Skip = strings.TrimSpace(input.Skip)+ input.Limit = strings.TrimSpace(input.Limit)++ if input.Skip == "" {+ input.Skip = "0"+ }+ if input.Limit == "" {+ input.Limit = "20"+ }+ return *input+}++// ToIndexParams converts the request into repositories.IndexParams.+func (input *ContactIndex) ToIndexParams() repositories.IndexParams {+ return repositories.IndexParams{+ Skip: input.getInt(input.Skip),+ Query: input.Query,+ SortBy: input.SortBy,+ SortDescending: input.SortDescending,+ Limit: input.getInt(input.Limit),+ }+}diff --git a/api/pkg/requests/contact_store.go b/api/pkg/requests/contact_store.gonew file mode 100644index 00000000..7ddf147b--- /dev/null+++ b/api/pkg/requests/contact_store.go@@ -0,0 +1,97 @@+package requests++import (+ "encoding/json"+ "strings"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/lib/pq"+)++// ContactItem is a single contact in a create request.+type ContactItem struct {+ Name string `json:"name" example:"Alice Smith"`+ Emails []string `json:"emails,omitempty"`+ PhoneNumbers []string `json:"phone_numbers"`+ Properties map[string]string `json:"properties,omitempty"`+}++// ContactStoreRequest creates one or many contacts.+type ContactStoreRequest struct {+ request+ Contacts []ContactItem `json:"contacts"`+}++// UnmarshalJSON accepts either a JSON array of contacts or {"contacts":[...]}.+func (input *ContactStoreRequest) UnmarshalJSON(data []byte) error {+ trimmed := strings.TrimSpace(string(data))+ if strings.HasPrefix(trimmed, "[") {+ var items []ContactItem+ if err := json.Unmarshal(data, &items); err != nil {+ return err+ }+ input.Contacts = items+ return nil+ }++ type alias ContactStoreRequest+ var wrapper alias+ if err := json.Unmarshal(data, &wrapper); err != nil {+ return err+ }++ input.Contacts = wrapper.Contacts+ return nil+}++// Sanitize trims and normalizes each contact item.+func (input ContactStoreRequest) Sanitize() ContactStoreRequest {+ for index := range input.Contacts {+ input.Contacts[index] = SanitizeContactItem(input.Contacts[index])+ }+ return input+}++// ToContacts converts the request into persistable entities.Contact records.+func (input *ContactStoreRequest) ToContacts(userID entities.UserID) []*entities.Contact {+ now := time.Now().UTC()+ contacts := make([]*entities.Contact, 0, len(input.Contacts))+ for _, item := range input.Contacts {+ properties := item.Properties+ if properties == nil {+ properties = map[string]string{}+ }++ contacts = append(contacts, &entities.Contact{+ ID: uuid.New(),+ UserID: userID,+ Name: item.Name,+ Emails: pq.StringArray(item.Emails),+ PhoneNumbers: pq.StringArray(item.PhoneNumbers),+ Properties: entities.ContactProperties(properties),+ CreatedAt: now,+ UpdatedAt: now,+ })+ }+ return contacts+}++// SanitizeContactItem trims and normalizes a single contact item so the CSV+// upload and JSON create paths accept and normalize identical values (e.g. a+// phone number without a leading "+" or an email with mixed case/whitespace).+func SanitizeContactItem(item ContactItem) ContactItem {+ item.Name = strings.TrimSpace(item.Name)+ item.Emails = sanitizeUniqueStrings(item.Emails, func(value string) string {+ return strings.ToLower(strings.TrimSpace(value))+ })+ item.PhoneNumbers = sanitizeUniqueStrings(item.PhoneNumbers, func(value string) string {+ var base request+ return base.sanitizeAddress(value)+ })+ if item.Properties == nil {+ item.Properties = map[string]string{}+ }+ return item+}diff --git a/api/pkg/requests/contact_store_test.go b/api/pkg/requests/contact_store_test.gonew file mode 100644index 00000000..85d20c07--- /dev/null+++ b/api/pkg/requests/contact_store_test.go@@ -0,0 +1,208 @@+package requests++import (+ "encoding/json"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestContactStoreRequest_UnmarshalArrayForm(t *testing.T) {+ var request ContactStoreRequest++ require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))++ require.Len(t, request.Contacts, 1)+ assert.Equal(t, "Alice", request.Contacts[0].Name)+ assert.Equal(t, []string{"+18005550199"}, request.Contacts[0].PhoneNumbers)+}++func TestContactStoreRequest_UnmarshalObjectForm(t *testing.T) {+ var request ContactStoreRequest++ require.NoError(t, json.Unmarshal([]byte(`{"contacts":[{"name":"Bob","phone_numbers":["+18005550100"]}]}`), &request))++ require.Len(t, request.Contacts, 1)+ assert.Equal(t, "Bob", request.Contacts[0].Name)+ assert.Equal(t, []string{"+18005550100"}, request.Contacts[0].PhoneNumbers)+}++func TestContactStoreRequest_UnmarshalMissingOptionalFields(t *testing.T) {+ var request ContactStoreRequest++ require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))++ require.Len(t, request.Contacts, 1)+ assert.Nil(t, request.Contacts[0].Emails)+ assert.Nil(t, request.Contacts[0].Properties)++ sanitized := request.Sanitize()+ require.Len(t, sanitized.Contacts, 1)+ assert.NotNil(t, sanitized.Contacts[0].Properties)+ assert.Empty(t, sanitized.Contacts[0].Properties)+}++func TestContactStoreRequest_UnmarshalMalformedJSON(t *testing.T) {+ var request ContactStoreRequest++ err := json.Unmarshal([]byte(`{"contacts":[{"name":"Alice"`), &request)++ require.Error(t, err)+}++func TestContactStoreRequest_SanitizeNormalizesAndDeduplicates(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: " Alice ",+ PhoneNumbers: []string{"18005550199", "+18005550199", " ", "+18005550100"},+ Emails: []string{" [email protected] ", "", "[email protected]", "[email protected]", "[email protected]"},+ Properties: map[string]string{"company": "Acme", "role": "CTO"},+ }}}++ request = request.Sanitize()++ require.Len(t, request.Contacts, 1)+ assert.Equal(t, "Alice", request.Contacts[0].Name)+ assert.Equal(t, []string{"+18005550199", "+18005550100"}, request.Contacts[0].PhoneNumbers)+ assert.Equal(t, []string{"[email protected]", "[email protected]"}, request.Contacts[0].Emails)+ assert.Equal(t, map[string]string{"company": "Acme", "role": "CTO"}, request.Contacts[0].Properties)+}++func TestContactStoreRequest_SanitizeInitializesNilProperties(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ }}}++ request = request.Sanitize()++ require.Len(t, request.Contacts, 1)+ assert.NotNil(t, request.Contacts[0].Properties)+ assert.Empty(t, request.Contacts[0].Properties)+}++func TestContactStoreRequest_ToContactsPreservesPropertiesAndOwnership(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: "Alice",+ Emails: []string{"[email protected]"},+ PhoneNumbers: []string{"+18005550199"},+ Properties: map[string]string{"company": "Acme"},+ }}}.Sanitize()++ contacts := request.ToContacts(entities.UserID("user-1"))++ require.Len(t, contacts, 1)+ assert.NotZero(t, contacts[0].ID)+ assert.Equal(t, entities.UserID("user-1"), contacts[0].UserID)+ assert.Equal(t, "Alice", contacts[0].Name)+ assert.Equal(t, []string{"[email protected]"}, []string(contacts[0].Emails))+ assert.Equal(t, []string{"+18005550199"}, []string(contacts[0].PhoneNumbers))+ assert.Equal(t, entities.ContactProperties{"company": "Acme"}, contacts[0].Properties)+ assert.False(t, contacts[0].CreatedAt.IsZero())+ assert.False(t, contacts[0].UpdatedAt.IsZero())+ assert.True(t, contacts[0].CreatedAt.Equal(contacts[0].UpdatedAt))+}++func TestContactStoreRequest_ToContactsInitializesNilProperties(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ }}}++ contacts := request.ToContacts(entities.UserID("user-1"))++ require.Len(t, contacts, 1)+ assert.NotNil(t, contacts[0].Properties)+ assert.Empty(t, contacts[0].Properties)+}++func TestContactUpdateRequest_SanitizeAndApplyTo(t *testing.T) {+ request := ContactUpdateRequest{+ Name: " Alice ",+ Emails: []string{" [email protected] ", "", "[email protected]"},+ PhoneNumbers: []string{"18005550199", "+18005550199"},+ Properties: map[string]string{"nickname": "Al"},+ }.Sanitize()++ contact := &entities.Contact{+ ID: uuid.MustParse("32343a19-da5e-4b1b-a767-3298a73703cb"),+ UserID: entities.UserID("user-1"),+ Name: "Before",+ Emails: nil,+ PhoneNumbers: nil,+ Properties: entities.ContactProperties{"old": "value"},+ CreatedAt: time.Unix(1, 0).UTC(),+ UpdatedAt: time.Unix(2, 0).UTC(),+ }++ request.ApplyTo(contact)++ assert.Equal(t, "Alice", contact.Name)+ assert.Equal(t, []string{"[email protected]"}, []string(contact.Emails))+ assert.Equal(t, []string{"+18005550199"}, []string(contact.PhoneNumbers))+ assert.Equal(t, entities.ContactProperties{"nickname": "Al"}, contact.Properties)+ assert.Equal(t, time.Unix(1, 0).UTC(), contact.CreatedAt)+ assert.True(t, contact.UpdatedAt.After(time.Unix(2, 0).UTC()))+}++func TestContactUpdateRequest_InitializesNilProperties(t *testing.T) {+ request := ContactUpdateRequest{Name: "Alice", PhoneNumbers: []string{"+18005550199"}}.Sanitize()++ assert.NotNil(t, request.Properties)+ assert.Empty(t, request.Properties)+}++func TestContactUpdateRequest_UnmarshalMissingOptionalFields(t *testing.T) {+ var request ContactUpdateRequest++ require.NoError(t, json.Unmarshal([]byte(`{"name":"Alice","phone_numbers":["+18005550199"]}`), &request))++ assert.Nil(t, request.Emails)+ assert.Nil(t, request.Properties)++ sanitized := request.Sanitize()+ assert.NotNil(t, sanitized.Properties)+ assert.Empty(t, sanitized.Properties)+}++func TestContactIndex_SanitizeUsesDefaultsAndToIndexParams(t *testing.T) {+ request := ContactIndex{}++ sanitized := request.Sanitize()+ params := sanitized.ToIndexParams()++ assert.Equal(t, "0", sanitized.Skip)+ assert.Equal(t, "20", sanitized.Limit)+ assert.Equal(t, "", sanitized.Query)+ assert.Equal(t, 0, params.Skip)+ assert.Equal(t, 20, params.Limit)+ assert.Equal(t, "", params.Query)+ assert.Equal(t, "", params.SortBy)+ assert.False(t, params.SortDescending)+}++func TestContactIndex_SanitizeTrimsAndConverts(t *testing.T) {+ request := ContactIndex{+ Skip: " 15 ",+ Limit: " 50 ",+ Query: " alice ",+ SortBy: " name ",+ SortDescending: true,+ }++ sanitized := request.Sanitize()+ params := sanitized.ToIndexParams()++ assert.Equal(t, "15", sanitized.Skip)+ assert.Equal(t, "50", sanitized.Limit)+ assert.Equal(t, "alice", sanitized.Query)+ assert.Equal(t, "name", sanitized.SortBy)+ assert.Equal(t, 15, params.Skip)+ assert.Equal(t, 50, params.Limit)+ assert.Equal(t, "alice", params.Query)+ assert.Equal(t, "name", params.SortBy)+ assert.True(t, params.SortDescending)+}diff --git a/api/pkg/requests/contact_update.go b/api/pkg/requests/contact_update.gonew file mode 100644index 00000000..55e34d60--- /dev/null+++ b/api/pkg/requests/contact_update.go@@ -0,0 +1,43 @@+package requests++import (+ "strings"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/lib/pq"+)++// ContactUpdateRequest updates an existing contact.+type ContactUpdateRequest struct {+ request+ Name string `json:"name" example:"Alice Smith"`+ Emails []string `json:"emails,omitempty"`+ PhoneNumbers []string `json:"phone_numbers"`+ Properties map[string]string `json:"properties,omitempty"`+}++// Sanitize trims and normalizes the update request.+func (input ContactUpdateRequest) Sanitize() ContactUpdateRequest {+ input.Name = strings.TrimSpace(input.Name)+ input.Emails = sanitizeUniqueStrings(input.Emails, func(value string) string {+ return strings.ToLower(strings.TrimSpace(value))+ })+ input.PhoneNumbers = sanitizeUniqueStrings(input.PhoneNumbers, func(value string) string {+ var base request+ return base.sanitizeAddress(value)+ })+ if input.Properties == nil {+ input.Properties = map[string]string{}+ }+ return input+}++// ApplyTo mutates an existing contact with the update values.+func (input *ContactUpdateRequest) ApplyTo(contact *entities.Contact) {+ contact.Name = input.Name+ contact.Emails = pq.StringArray(input.Emails)+ contact.PhoneNumbers = pq.StringArray(input.PhoneNumbers)+ contact.Properties = entities.ContactProperties(input.Properties)+ contact.UpdatedAt = time.Now().UTC()+}diff --git a/api/pkg/requests/message_thread_index_request.go b/api/pkg/requests/message_thread_index_request.goindex 53157df5..053f9000 100644--- a/api/pkg/requests/message_thread_index_request.go+++ b/api/pkg/requests/message_thread_index_request.go@@ -18,6 +18,7 @@ type MessageThreadIndex struct {Query string `json:"query" query:"query"`Limit string `json:"limit" query:"limit"`Owner string `json:"owner" query:"owner"`+ Contacts string `json:"contacts" query:"contacts" example:"false"`}// Sanitize sets defaults to MessageOutstanding@@ -30,7 +31,16 @@ func (input *MessageThreadIndex) Sanitize() MessageThreadIndex {input.IsArchived = "false"}+ if strings.TrimSpace(input.Contacts) == "" {+ input.Contacts = "false"+ }+input.IsArchived = input.sanitizeBool(input.IsArchived)+ input.Contacts = input.sanitizeBool(input.Contacts)+ if input.Contacts != "true" && input.Contacts != "false" {+ input.Contacts = "false"+ }+input.Query = strings.TrimSpace(input.Query)input.Owner = input.sanitizeAddress(input.Owner)@@ -50,8 +60,9 @@ func (input *MessageThreadIndex) ToGetParams(userID entities.UserID) services.MeQuery: input.Query,Limit: input.getInt(input.Limit),},- UserID: userID,- IsArchived: input.getBool(input.IsArchived),- Owner: input.Owner,+ UserID: userID,+ IsArchived: input.getBool(input.IsArchived),+ WithContacts: input.getBool(input.Contacts),+ Owner: input.Owner,}}diff --git a/api/pkg/requests/message_thread_index_request_test.go b/api/pkg/requests/message_thread_index_request_test.gonew file mode 100644index 00000000..fc7f7b0e--- /dev/null+++ b/api/pkg/requests/message_thread_index_request_test.go@@ -0,0 +1,40 @@+package requests++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/stretchr/testify/assert"+)++func TestMessageThreadIndex_ToGetParams_WithContactsTrue(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: " true "}).Sanitize()+ params := input.ToGetParams(entities.UserID("user-id"))++ assert.Equal(t, "true", input.Contacts)+ assert.True(t, params.WithContacts)+}++func TestMessageThreadIndex_ToGetParams_WithContactsFalse(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "0"}).Sanitize()+ params := input.ToGetParams(entities.UserID("user-id"))++ assert.Equal(t, "false", input.Contacts)+ assert.False(t, params.WithContacts)+}++func TestMessageThreadIndex_ToGetParams_WithContactsDefaultsFalse(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199"}).Sanitize()+ params := input.ToGetParams(entities.UserID("user-id"))++ assert.Equal(t, "false", input.Contacts)+ assert.False(t, params.WithContacts)+}++func TestMessageThreadIndex_ToGetParams_WithContactsInvalidNormalizesFalse(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "definitely"}).Sanitize()+ params := input.ToGetParams(entities.UserID("user-id"))++ assert.Equal(t, "false", input.Contacts)+ assert.False(t, params.WithContacts)+}diff --git a/api/pkg/requests/request.go b/api/pkg/requests/request.goindex 1db27861..af206683 100644--- a/api/pkg/requests/request.go+++ b/api/pkg/requests/request.go@@ -120,6 +120,24 @@ func (input *request) removeEmptyStrings(values []string) []string {return result}+func sanitizeUniqueStrings(values []string, normalize func(string) string) []string {+ seen := map[string]struct{}{}+ result := make([]string, 0, len(values))+ for _, value := range values {+ value = normalize(value)+ if value == "" {+ continue+ }+ if _, ok := seen[value]; ok {+ continue+ }+ seen[value] = struct{}{}+ result = append(result, value)+ }++ return result+}+func (input *request) sanitizeMessageID(value string) string {id := strings.Builder{}for _, char := range value {diff --git a/api/pkg/responses/contact_responses.go b/api/pkg/responses/contact_responses.gonew file mode 100644index 00000000..09db7884--- /dev/null+++ b/api/pkg/responses/contact_responses.go@@ -0,0 +1,24 @@+package responses++import "github.com/NdoleStudio/httpsms/pkg/entities"++// ContactResponse is the payload containing entities.Contact.+type ContactResponse struct {+ response+ Data entities.Contact `json:"data"`+}++// ContactsCreatedResponse is the payload returned after creating contacts.+type ContactsCreatedResponse struct {+ response+ Data []entities.Contact `json:"data"`+}++// ContactsResponse is the payload containing []entities.Contact.+type ContactsResponse struct {+ response+ Data []entities.Contact `json:"data"`+ // Total is the number of contacts matching the request filter for the+ // user, independent of the pagination skip/limit applied to Data.+ Total int64 `json:"total" example:"57"`+}diff --git a/api/pkg/services/contact_service.go b/api/pkg/services/contact_service.gonew file mode 100644index 00000000..de6fa40f--- /dev/null+++ b/api/pkg/services/contact_service.go@@ -0,0 +1,288 @@+package services++import (+ "context"+ "fmt"+ "sync"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/dgraph-io/ristretto/v2"+ "github.com/google/uuid"+)++// contactMapCacheTTL bounds cross-instance staleness because invalidation is process-local.+const (+ contactMapCacheTTL = 5 * time.Minute+ contactGenerationCleanupInterval = time.Hour+)++// ContactCacheEntry stores a contact together with its user's cache generation.+type ContactCacheEntry struct {+ contact *entities.Contact+ generation uint64+}++type contactGeneration struct {+ value uint64+ lastAccess time.Time+}++// ContactService owns contact CRUD and phone-number contact lookups.+type ContactService struct {+ service+ logger telemetry.Logger+ tracer telemetry.Tracer+ repository repositories.ContactRepository+ cache *ristretto.Cache[string, ContactCacheEntry]+ generationMu sync.Mutex+ generations map[entities.UserID]contactGeneration+ nextGeneration uint64+ lastGenerationCleanup time.Time+}++// NewContactService creates a new ContactService.+func NewContactService(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ repository repositories.ContactRepository,+ contactCache *ristretto.Cache[string, ContactCacheEntry],+) (s *ContactService) {+ return &ContactService{+ logger: logger.WithService(fmt.Sprintf("%T", s)),+ tracer: tracer,+ repository: repository,+ cache: contactCache,+ generations: make(map[entities.UserID]contactGeneration),+ }+}++func (service *ContactService) cacheKey(userID entities.UserID, phoneNumber string) string {+ return fmt.Sprintf("%s|%s", userID, phoneNumber)+}++func (service *ContactService) generation(userID entities.UserID) uint64 {+ now := time.Now()+ service.generationMu.Lock()+ defer service.generationMu.Unlock()++ service.expireGenerationsLocked(now)+ if generation, ok := service.generations[userID]; ok {+ generation.lastAccess = now+ service.generations[userID] = generation+ return generation.value+ }++ service.nextGeneration+++ service.generations[userID] = contactGeneration{+ value: service.nextGeneration,+ lastAccess: now,+ }+ return service.nextGeneration+}++func (service *ContactService) advanceGeneration(userID entities.UserID) {+ now := time.Now()+ service.generationMu.Lock()+ defer service.generationMu.Unlock()++ service.expireGenerationsLocked(now)+ service.nextGeneration+++ service.generations[userID] = contactGeneration{+ value: service.nextGeneration,+ lastAccess: now,+ }+}++func (service *ContactService) expireGenerations(now time.Time) {+ service.generationMu.Lock()+ defer service.generationMu.Unlock()+ service.expireGenerationsLocked(now)+}++func (service *ContactService) expireGenerationsLocked(now time.Time) {+ if !service.lastGenerationCleanup.IsZero() &&+ now.Sub(service.lastGenerationCleanup) < contactGenerationCleanupInterval {+ return+ }+ for userID, generation := range service.generations {+ if now.Sub(generation.lastAccess) >= contactMapCacheTTL {+ delete(service.generations, userID)+ }+ }+ service.lastGenerationCleanup = now+}++// CreateMany persists one or many contacts in a single batch.+func (service *ContactService) CreateMany(ctx context.Context, userID entities.UserID, contacts []*entities.Contact) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.Store(ctx, contacts); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts for user [%s]", len(contacts), userID))+ }++ phoneNumbers := make([]string, 0)+ for _, contact := range contacts {+ phoneNumbers = append(phoneNumbers, contact.PhoneNumbers...)+ }+ service.invalidate(userID, phoneNumbers)+ return nil+}++// Get returns a single contact scoped to the user.+func (service *ContactService) Get(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ contact, err := service.repository.Load(ctx, userID, contactID)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, stacktrace.GetCode(err), "cannot load contact [%s] for user [%s]", contactID, userID))+ }+ return contact, nil+}++// Index lists contacts for a user with the provided search/pagination params.+func (service *ContactService) Index(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ contacts, err := service.repository.Index(ctx, userID, params)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s]", userID))+ }+ return contacts, nil+}++// Count returns the total number of contacts for a user matching the same+// search filter as Index, ignoring pagination. It lets callers report an+// accurate total independent of the current page's skip/limit.+func (service *ContactService) Count(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (int64, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ total, err := service.repository.Count(ctx, userID, params)+ if err != nil {+ return 0, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot count contacts for user [%s]", userID))+ }+ return total, nil+}++// Update persists changes to a contact and invalidates its old and new numbers.+func (service *ContactService) Update(ctx context.Context, contact *entities.Contact, previousPhoneNumbers []string) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.Update(ctx, contact); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact [%s] for user [%s]", contact.ID, contact.UserID))+ }++ phoneNumbers := make([]string, 0, len(previousPhoneNumbers)+len(contact.PhoneNumbers))+ phoneNumbers = append(phoneNumbers, previousPhoneNumbers...)+ phoneNumbers = append(phoneNumbers, contact.PhoneNumbers...)+ service.invalidate(contact.UserID, phoneNumbers)+ return nil+}++// Delete removes a contact scoped to the user and invalidates its phone numbers.+func (service *ContactService) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ contact, err := service.repository.Load(ctx, userID, contactID)+ if err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, stacktrace.GetCode(err), "cannot load contact [%s] for user [%s] before delete", contactID, userID))+ }++ if err := service.repository.Delete(ctx, userID, contactID); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))+ }++ service.invalidate(userID, contact.PhoneNumbers)+ return nil+}++// DeleteAllForUser removes every contact owned by a user and clears cached contacts.+func (service *ContactService) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.DeleteAllForUser(ctx, userID); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))+ }++ service.invalidate(userID, nil)+ return nil+}++// GetContactMap resolves only the requested phone numbers. Each contact is+// cached independently by user and phone number.+func (service *ContactService) GetContactMap(ctx context.Context, userID entities.UserID, phoneNumbers []string) (map[string]*entities.Contact, error) {+ ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)+ defer span.End()++ generation := service.generation(userID)+ result := make(map[string]*entities.Contact, len(phoneNumbers))+ missing := make([]string, 0, len(phoneNumbers))+ missingSet := make(map[string]struct{}, len(phoneNumbers))+ requested := make(map[string]struct{}, len(phoneNumbers))+ for _, phoneNumber := range phoneNumbers {+ if _, seen := requested[phoneNumber]; seen {+ continue+ }+ requested[phoneNumber] = struct{}{}+ key := service.cacheKey(userID, phoneNumber)+ if entry, found := service.cache.Get(key); found {+ if entry.generation == generation {+ if entry.contact != nil {+ result[phoneNumber] = entry.contact+ }+ continue+ }+ service.cache.Del(key)+ }+ missing = append(missing, phoneNumber)+ missingSet[phoneNumber] = struct{}{}+ }++ if len(missing) == 0 {+ return result, nil+ }++ contacts, err := service.repository.FetchByPhoneNumbers(ctx, userID, missing)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts by phone numbers for user [%s]", userID))+ }++ for index := range *contacts {+ contact := (*contacts)[index]+ for _, phoneNumber := range contact.PhoneNumbers {+ if _, requested := missingSet[phoneNumber]; requested {+ result[phoneNumber] = &contact+ }+ }+ }++ if service.generation(userID) == generation {+ for _, phoneNumber := range missing {+ contact := result[phoneNumber]+ entry := ContactCacheEntry{contact: contact, generation: generation}+ if accepted := service.cache.SetWithTTL(service.cacheKey(userID, phoneNumber), entry, 1, contactMapCacheTTL); !accepted {+ ctxLogger.Error(stacktrace.NewErrorf("cannot cache contact lookup for user [%s] and phone number [%s]", userID, phoneNumber))+ }+ }+ }++ return result, nil+}++func (service *ContactService) invalidate(userID entities.UserID, phoneNumbers []string) {+ service.advanceGeneration(userID)+ service.cache.Wait()+ for _, phoneNumber := range phoneNumbers {+ service.cache.Del(service.cacheKey(userID, phoneNumber))+ }+}diff --git a/api/pkg/services/contact_service_test.go b/api/pkg/services/contact_service_test.gonew file mode 100644index 00000000..2c549803--- /dev/null+++ b/api/pkg/services/contact_service_test.go@@ -0,0 +1,598 @@+package services++import (+ "context"+ "errors"+ "sync"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/dgraph-io/ristretto/v2"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "go.opentelemetry.io/otel/trace"+)++// --- fake repository --------------------------------------------------------++type fakeContactRepo struct {+ mu sync.Mutex++ contacts []*entities.Contact++ storeCalls [][]*entities.Contact+ updateCalls []*entities.Contact+ loadCalls []loadCall+ indexCalls []indexCall+ countCalls []indexCall+ deleteCalls []deleteCall+ deleteAllCalls []entities.UserID+ fetchCalls []fetchCall++ storeErr error+ updateErr error+ loadErr error+ indexErr error+ countErr error+ deleteErr error+ deleteAllErr error+ fetchErr error++ indexResult []entities.Contact+ countResult int64+}++type loadCall struct {+ userID entities.UserID+ id uuid.UUID+}++type indexCall struct {+ userID entities.UserID+ params repositories.IndexParams+}++type deleteCall struct {+ userID entities.UserID+ id uuid.UUID+}++type fetchCall struct {+ userID entities.UserID+ phoneNumbers []string+}++type blockingContactRepo struct {+ *fakeContactRepo+ fetchStarted chan struct{}+ releaseFetch chan struct{}+ fetchOnce sync.Once+}++func (r *blockingContactRepo) FetchByPhoneNumbers(ctx context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error) {+ var captured []entities.Contact+ r.fetchOnce.Do(func() {+ r.fakeContactRepo.mu.Lock()+ captured = append(captured, *r.fakeContactRepo.contacts[0])+ r.fakeContactRepo.mu.Unlock()+ close(r.fetchStarted)+ <-r.releaseFetch+ })+ if captured != nil {+ return &captured, nil+ }+ return r.fakeContactRepo.FetchByPhoneNumbers(ctx, userID, phoneNumbers)+}++func (r *fakeContactRepo) Store(_ context.Context, contacts []*entities.Contact) error {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.storeCalls = append(r.storeCalls, contacts)+ if r.storeErr != nil {+ return r.storeErr+ }+ r.contacts = append(r.contacts, contacts...)+ return nil+}++func (r *fakeContactRepo) Update(_ context.Context, contact *entities.Contact) error {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.updateCalls = append(r.updateCalls, contact)+ if r.updateErr != nil {+ return r.updateErr+ }+ for index := range r.contacts {+ if r.contacts[index].ID == contact.ID && r.contacts[index].UserID == contact.UserID {+ clone := *contact+ r.contacts[index] = &clone+ break+ }+ }+ return nil+}++func (r *fakeContactRepo) Load(_ context.Context, userID entities.UserID, id uuid.UUID) (*entities.Contact, error) {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.loadCalls = append(r.loadCalls, loadCall{userID: userID, id: id})+ if r.loadErr != nil {+ return nil, r.loadErr+ }+ for _, c := range r.contacts {+ if c.ID == id && c.UserID == userID {+ return c, nil+ }+ }+ return nil, stacktrace.NewErrorWithCodef(repositories.ErrCodeNotFound, "contact [%s] not found", id)+}++func (r *fakeContactRepo) Index(_ context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.indexCalls = append(r.indexCalls, indexCall{userID: userID, params: params})+ if r.indexErr != nil {+ return nil, r.indexErr+ }+ out := append([]entities.Contact{}, r.indexResult...)+ return &out, nil+}++func (r *fakeContactRepo) Count(_ context.Context, userID entities.UserID, params repositories.IndexParams) (int64, error) {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.countCalls = append(r.countCalls, indexCall{userID: userID, params: params})+ if r.countErr != nil {+ return 0, r.countErr+ }+ return r.countResult, nil+}++func (r *fakeContactRepo) FetchByPhoneNumbers(_ context.Context, userID entities.UserID, phoneNumbers []string) (*[]entities.Contact, error) {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.fetchCalls = append(r.fetchCalls, fetchCall{+ userID: userID,+ phoneNumbers: append([]string{}, phoneNumbers...),+ })+ if r.fetchErr != nil {+ return nil, r.fetchErr+ }+ requested := make(map[string]struct{}, len(phoneNumbers))+ for _, phoneNumber := range phoneNumbers {+ requested[phoneNumber] = struct{}{}+ }++ out := make([]entities.Contact, 0)+ for _, c := range r.contacts {+ if c.UserID != userID {+ continue+ }+ for _, phoneNumber := range c.PhoneNumbers {+ if _, ok := requested[phoneNumber]; ok {+ out = append(out, *c)+ break+ }+ }+ }+ return &out, nil+}++func (r *fakeContactRepo) Delete(_ context.Context, userID entities.UserID, id uuid.UUID) error {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.deleteCalls = append(r.deleteCalls, deleteCall{userID: userID, id: id})+ return r.deleteErr+}++func (r *fakeContactRepo) DeleteAllForUser(_ context.Context, userID entities.UserID) error {+ r.mu.Lock()+ defer r.mu.Unlock()++ r.deleteAllCalls = append(r.deleteAllCalls, userID)+ if r.deleteAllErr != nil {+ return r.deleteAllErr+ }+ remaining := r.contacts[:0]+ for _, contact := range r.contacts {+ if contact.UserID != userID {+ remaining = append(remaining, contact)+ }+ }+ r.contacts = remaining+ return nil+}++type recordingLogger struct {+ *noopLogger+ mu sync.Mutex+ errors []error+ warns []error+ infos []string+ debugs []string+}++func newRecordingLogger() *recordingLogger {+ return &recordingLogger{noopLogger: &noopLogger{}}+}++func (l *recordingLogger) Error(err error) {+ l.mu.Lock()+ defer l.mu.Unlock()+ l.errors = append(l.errors, err)+}++func (l *recordingLogger) Warn(err error) {+ l.mu.Lock()+ defer l.mu.Unlock()+ l.warns = append(l.warns, err)+}++func (l *recordingLogger) Info(v string) {+ l.mu.Lock()+ defer l.mu.Unlock()+ l.infos = append(l.infos, v)+}++func (l *recordingLogger) Debug(v string) {+ l.mu.Lock()+ defer l.mu.Unlock()+ l.debugs = append(l.debugs, v)+}++func (l *recordingLogger) WithService(_ string) telemetry.Logger { return l }+func (l *recordingLogger) WithString(_, _ string) telemetry.Logger { return l }+func (l *recordingLogger) WithSpan(_ trace.SpanContext) telemetry.Logger {+ return l+}++// --- helpers ---------------------------------------------------------------++func newContactCache(t *testing.T) *ristretto.Cache[string, ContactCacheEntry] {+ t.Helper()++ contactCache, err := ristretto.NewCache[string, ContactCacheEntry](&ristretto.Config[string, ContactCacheEntry]{+ MaxCost: 100,+ NumCounters: 1_000,+ BufferItems: 64,+ })+ require.NoError(t, err)+ t.Cleanup(contactCache.Close)+ return contactCache+}++func newContactServiceForTest(t *testing.T, repo repositories.ContactRepository, logger telemetry.Logger) *ContactService {+ t.Helper()+ if logger == nil {+ logger = &noopLogger{}+ }+ tracer := telemetry.NewOtelLogger("test", logger)+ return NewContactService(logger, tracer, repo, newContactCache(t))+}++// --- tests -----------------------------------------------------------------++func TestContactService_GetContactMap_FetchesOnlyUncachedPhoneNumbers(t *testing.T) {+ repo := &fakeContactRepo{contacts: []*entities.Contact{+ {ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},+ {ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},+ {ID: uuid.New(), UserID: "u1", Name: "Carol", PhoneNumbers: pq.StringArray{"+18005550111"}},+ }}+ service := newContactServiceForTest(t, repo, nil)++ first, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{"+18005550199"})+ require.NoError(t, err)+ service.cache.Wait()+ require.Len(t, first, 1)++ second, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{"+18005550199", "+18005550111"})+ require.NoError(t, err)++ require.Len(t, repo.fetchCalls, 2)+ assert.Equal(t, []string{"+18005550199"}, repo.fetchCalls[0].phoneNumbers)+ assert.Equal(t, []string{"+18005550111"}, repo.fetchCalls[1].phoneNumbers)+ assert.Equal(t, "Carol", second["+18005550111"].Name)+}++func TestContactService_GetContactMap_CacheKeyIncludesUserAndPhoneNumber(t *testing.T) {+ number := "+18005550199"+ repo := &fakeContactRepo{contacts: []*entities.Contact{+ {ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{number}},+ {ID: uuid.New(), UserID: "u2", Name: "Bob", PhoneNumbers: pq.StringArray{number}},+ }}+ service := newContactServiceForTest(t, repo, nil)++ first, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ require.NoError(t, err)+ service.cache.Wait()+ second, err := service.GetContactMap(context.Background(), entities.UserID("u2"), []string{number})+ require.NoError(t, err)++ assert.Equal(t, "Alice", first[number].Name)+ assert.Equal(t, "Bob", second[number].Name)+ require.Len(t, repo.fetchCalls, 2)+}++func TestContactService_GetContactMap_CachesMissingPhoneNumbers(t *testing.T) {+ repo := &fakeContactRepo{}+ service := newContactServiceForTest(t, repo, nil)+ number := "+18005550199"++ first, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ require.NoError(t, err)+ service.cache.Wait()+ second, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ require.NoError(t, err)++ assert.Empty(t, first)+ assert.Empty(t, second)+ require.Len(t, repo.fetchCalls, 1)+}++func TestContactService_ExpiresInactiveGenerationStateWithoutReusingEpoch(t *testing.T) {+ service := newContactServiceForTest(t, &fakeContactRepo{}, nil)++ first := service.generation(entities.UserID("u1"))+ service.expireGenerations(time.Now().Add(contactMapCacheTTL + time.Hour))+ second := service.generation(entities.UserID("u1"))++ assert.NotEqual(t, first, second)+}++func TestContactService_GetContactMap_TieBreakMostRecentlyUpdatedWins(t *testing.T) {+ number := "+18005550199"+ older := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Old", PhoneNumbers: pq.StringArray{number}, UpdatedAt: time.Now().Add(-time.Hour)}+ newer := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "New", PhoneNumbers: pq.StringArray{number}, UpdatedAt: time.Now()}+ repo := &fakeContactRepo{contacts: []*entities.Contact{older, newer}}+ service := newContactServiceForTest(t, repo, nil)++ result, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ require.NoError(t, err)++ require.NotNil(t, result[number])+ assert.Equal(t, newer.ID, result[number].ID)+}++func TestContactService_Update_InvalidatesOldAndNewPhoneNumbers(t *testing.T) {+ oldNumber := "+18005550199"+ newNumber := "+18005550100"+ id := uuid.New()+ repo := &fakeContactRepo{contacts: []*entities.Contact{{+ ID: id, UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{oldNumber},+ }}}+ contactCache := newContactCache(t)+ stale := &entities.Contact{ID: id, UserID: "u1", Name: "Stale"}+ require.True(t, contactCache.Set("u1|"+oldNumber, ContactCacheEntry{contact: stale}, 1))+ require.True(t, contactCache.Set("u1|"+newNumber, ContactCacheEntry{contact: stale}, 1))+ contactCache.Wait()+ logger := &noopLogger{}+ service := NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, contactCache)++ err := service.Update(context.Background(), &entities.Contact{+ ID: id, UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{newNumber},+ }, []string{oldNumber})+ require.NoError(t, err)+ contactCache.Wait()++ _, oldFound := contactCache.Get("u1|" + oldNumber)+ _, newFound := contactCache.Get("u1|" + newNumber)+ assert.False(t, oldFound)+ assert.False(t, newFound)+}++func TestContactService_GetContactMap_DoesNotReuseResultFetchedDuringUpdate(t *testing.T) {+ number := "+18005550199"+ id := uuid.New()+ repo := &blockingContactRepo{+ fakeContactRepo: &fakeContactRepo{contacts: []*entities.Contact{{+ ID: id, UserID: "u1", Name: "Old", PhoneNumbers: pq.StringArray{number},+ }}},+ fetchStarted: make(chan struct{}),+ releaseFetch: make(chan struct{}),+ }+ service := newContactServiceForTest(t, repo, nil)++ firstResult := make(chan map[string]*entities.Contact, 1)+ go func() {+ result, _ := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ firstResult <- result+ }()+ <-repo.fetchStarted++ require.NoError(t, service.Update(context.Background(), &entities.Contact{+ ID: id, UserID: "u1", Name: "New", PhoneNumbers: pq.StringArray{number},+ }, []string{number}))+ close(repo.releaseFetch)+ assert.Equal(t, "Old", (<-firstResult)[number].Name)+ service.cache.Wait()++ second, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{number})+ require.NoError(t, err)+ assert.Equal(t, "New", second[number].Name)+}++func TestContactService_DeleteAllForUser_DoesNotEvictOtherUsers(t *testing.T) {+ repo := &fakeContactRepo{contacts: []*entities.Contact{+ {UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},+ {UserID: "u2", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},+ }}+ contactCache := newContactCache(t)+ logger := &noopLogger{}+ service := NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, contactCache)+ require.True(t, contactCache.Set("u1|+18005550199", ContactCacheEntry{+ contact: repo.contacts[0], generation: service.generation("u1"),+ }, 1))+ require.True(t, contactCache.Set("u2|+18005550100", ContactCacheEntry{+ contact: repo.contacts[1], generation: service.generation("u2"),+ }, 1))+ contactCache.Wait()++ require.NoError(t, service.DeleteAllForUser(context.Background(), entities.UserID("u1")))++ first, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{"+18005550199"})+ require.NoError(t, err)+ second, err := service.GetContactMap(context.Background(), entities.UserID("u2"), []string{"+18005550100"})+ require.NoError(t, err)+ assert.Empty(t, first)+ assert.Equal(t, "Bob", second["+18005550100"].Name)+ require.Len(t, repo.fetchCalls, 1)+ assert.Equal(t, entities.UserID("u1"), repo.fetchCalls[0].userID)+}++// --- CRUD delegation and user scope tests ---------------------------------++func TestContactService_CreateMany_PersistsBatchInSingleCall(t *testing.T) {+ repo := &fakeContactRepo{}+ service := newContactServiceForTest(t, repo, nil)++ batch := []*entities.Contact{+ {ID: uuid.New(), UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"}},+ {ID: uuid.New(), UserID: "u1", Name: "B", PhoneNumbers: pq.StringArray{"+18005550111"}},+ }+ require.NoError(t, service.CreateMany(context.Background(), entities.UserID("u1"), batch))++ require.Len(t, repo.storeCalls, 1)+ assert.Equal(t, batch, repo.storeCalls[0])+}++func TestContactService_CreateMany_RepositoryErrorIsWrapped(t *testing.T) {+ repo := &fakeContactRepo{storeErr: errors.New("db down")}+ service := newContactServiceForTest(t, repo, nil)++ err := service.CreateMany(context.Background(), entities.UserID("u1"), []*entities.Contact{{+ ID: uuid.New(), UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"},+ }})+ require.Error(t, err)+ assert.Contains(t, err.Error(), "db down")+}++func TestContactService_Get_DelegatesWithUserScope(t *testing.T) {+ id := uuid.New()+ other := uuid.New()+ repo := &fakeContactRepo{contacts: []*entities.Contact{+ {ID: id, UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}},+ {ID: other, UserID: "u2", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}},+ }}+ service := newContactServiceForTest(t, repo, nil)++ got, err := service.Get(context.Background(), entities.UserID("u1"), id)+ require.NoError(t, err)+ assert.Equal(t, "Alice", got.Name)++ // Wrong user scope must not resolve the contact.+ _, err = service.Get(context.Background(), entities.UserID("u1"), other)+ require.Error(t, err)+ assert.Equal(t, repositories.ErrCodeNotFound, stacktrace.GetCode(err))+}++func TestContactService_Index_DelegatesParams(t *testing.T) {+ want := []entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}+ repo := &fakeContactRepo{indexResult: want}+ service := newContactServiceForTest(t, repo, nil)++ params := repositories.IndexParams{Skip: 5, Limit: 10, SortBy: "name", Query: "Ali"}+ got, err := service.Index(context.Background(), entities.UserID("u1"), params)+ require.NoError(t, err)+ require.NotNil(t, got)+ assert.Equal(t, want, *got)++ require.Len(t, repo.indexCalls, 1)+ assert.Equal(t, entities.UserID("u1"), repo.indexCalls[0].userID)+ assert.Equal(t, params, repo.indexCalls[0].params)+}++func TestContactService_Index_RepositoryErrorIsWrapped(t *testing.T) {+ repo := &fakeContactRepo{indexErr: errors.New("index boom")}+ service := newContactServiceForTest(t, repo, nil)++ _, err := service.Index(context.Background(), entities.UserID("u1"), repositories.IndexParams{})+ require.Error(t, err)+ assert.Contains(t, err.Error(), "index boom")+}++func TestContactService_Count_DelegatesParamsAndReturnsTotal(t *testing.T) {+ repo := &fakeContactRepo{countResult: 57}+ service := newContactServiceForTest(t, repo, nil)++ params := repositories.IndexParams{Skip: 5, Limit: 10, Query: "Ali"}+ total, err := service.Count(context.Background(), entities.UserID("u1"), params)+ require.NoError(t, err)+ assert.Equal(t, int64(57), total)++ require.Len(t, repo.countCalls, 1)+ assert.Equal(t, entities.UserID("u1"), repo.countCalls[0].userID)+ assert.Equal(t, params, repo.countCalls[0].params)+}++func TestContactService_Count_RepositoryErrorIsWrapped(t *testing.T) {+ repo := &fakeContactRepo{countErr: errors.New("count boom")}+ service := newContactServiceForTest(t, repo, nil)++ _, err := service.Count(context.Background(), entities.UserID("u1"), repositories.IndexParams{})+ require.Error(t, err)+ assert.Contains(t, err.Error(), "count boom")+}++func TestContactService_Update_RepositoryErrorIsWrappedAndSkipsInvalidation(t *testing.T) {+ id := uuid.New()+ repo := &fakeContactRepo{+ contacts: []*entities.Contact{{ID: id, UserID: "u1", PhoneNumbers: pq.StringArray{"+18005550100"}}},+ updateErr: errors.New("update boom"),+ }+ contactCache := newContactCache(t)+ require.True(t, contactCache.Set("u1|+18005550100", ContactCacheEntry{contact: &entities.Contact{Name: "Cached"}}, 1))+ contactCache.Wait()+ logger := &noopLogger{}+ service := NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, contactCache)++ err := service.Update(+ context.Background(),+ &entities.Contact{ID: id, UserID: "u1", Name: "A", PhoneNumbers: pq.StringArray{"+18005550100"}},+ []string{"+18005550100"},+ )+ require.Error(t, err)+ assert.Contains(t, err.Error(), "update boom")+ _, found := contactCache.Get("u1|+18005550100")+ assert.True(t, found, "invalidation must not run when the write fails")+}++func TestContactService_Delete_RepositoryErrorIsWrappedAndSkipsInvalidation(t *testing.T) {+ id := uuid.New()+ repo := &fakeContactRepo{+ contacts: []*entities.Contact{{ID: id, UserID: "u1", PhoneNumbers: pq.StringArray{"+18005550100"}}},+ deleteErr: errors.New("delete boom"),+ }+ contactCache := newContactCache(t)+ require.True(t, contactCache.Set("u1|+18005550100", ContactCacheEntry{contact: &entities.Contact{Name: "Cached"}}, 1))+ contactCache.Wait()+ logger := &noopLogger{}+ service := NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, contactCache)++ err := service.Delete(context.Background(), entities.UserID("u1"), id)+ require.Error(t, err)+ assert.Contains(t, err.Error(), "delete boom")+ _, found := contactCache.Get("u1|+18005550100")+ assert.True(t, found, "invalidation must not run when the write fails")+}++func TestContactService_GetContactMap_FetchErrorIsWrapped(t *testing.T) {+ repo := &fakeContactRepo{fetchErr: errors.New("fetch boom")}+ service := newContactServiceForTest(t, repo, nil)++ _, err := service.GetContactMap(context.Background(), entities.UserID("u1"), []string{"+18005550100"})+ require.Error(t, err)+ assert.Contains(t, err.Error(), "fetch boom")+}diff --git a/api/pkg/services/entitlement_service.go b/api/pkg/services/entitlement_service.goindex 96a5af14..01ddf441 100644--- a/api/pkg/services/entitlement_service.go+++ b/api/pkg/services/entitlement_service.go@@ -62,6 +62,18 @@ func (service *EntitlementService) Check(userID entities.UserID,entityName string,countFunc func() (int, error),+) (*EntitlementCheckResult, error) {+ return service.CheckAdditional(ctx, userID, entityName, 1, countFunc)+}++// CheckAdditional verifies if the user can create additionalCount instances of+// the given entity without exceeding their subscription plan limit.+func (service *EntitlementService) CheckAdditional(+ ctx context.Context,+ userID entities.UserID,+ entityName string,+ additionalCount int,+ countFunc func() (int, error),) (*EntitlementCheckResult, error) {ctx, span := service.tracer.Start(ctx)defer span.End()@@ -70,8 +82,8 @@ func (service *EntitlementService) Check(return &EntitlementCheckResult{Allowed: true}, nil}- limits, exists := entityLimits[entityName]- if !exists {+ limits, hasConfiguredLimits := entityLimits[entityName]+ if !hasConfiguredLimits && entityName != entities.EntityNameContact {return &EntitlementCheckResult{Allowed: true}, nil}@@ -83,9 +95,13 @@ func (service *EntitlementService) Check()}- limit, hasLimit := limits[user.SubscriptionName]- if !hasLimit || limit == 0 {- return &EntitlementCheckResult{Allowed: true}, nil+ limit := int(user.SubscriptionName.Limit())+ if entityName != entities.EntityNameContact {+ var hasLimit bool+ limit, hasLimit = limits[user.SubscriptionName]+ if !hasLimit || limit == 0 {+ return &EntitlementCheckResult{Allowed: true}, nil+ }}currentCount, err := countFunc()@@ -96,11 +112,11 @@ func (service *EntitlementService) Check()}- if currentCount >= limit {+ if currentCount+additionalCount > limit {return &EntitlementCheckResult{Allowed: false,Message: fmt.Sprintf(- "Upgrade to a paid plan to create more than [%d] %s. Visit https://httpsms.com/pricing for details.",+ "Upgrade your plan to create more than [%d] %s. Visit https://httpsms.com/pricing for details.",limit,formatEntityName(entityName, true),),diff --git a/api/pkg/services/entitlement_service_test.go b/api/pkg/services/entitlement_service_test.gonew file mode 100644index 00000000..18967cb4--- /dev/null+++ b/api/pkg/services/entitlement_service_test.go@@ -0,0 +1,104 @@+package services++import (+ "context"+ "strconv"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type entitlementUserRepository struct {+ repositories.UserRepository+ user *entities.User+ loadCalls int+}++func (repository *entitlementUserRepository) Load(_ context.Context, _ entities.UserID) (*entities.User, error) {+ repository.loadCalls+++ return repository.user, nil+}++func newEntitlementServiceForTest(enabled bool, repository repositories.UserRepository) *EntitlementService {+ logger := newRecordingLogger()+ return NewEntitlementService(logger, telemetry.NewOtelLogger("test", logger), enabled, repository)+}++func TestEntitlementService_CheckAdditional_DisabledAllowsWithoutLoadingUserOrCount(t *testing.T) {+ repository := &entitlementUserRepository{}+ service := newEntitlementServiceForTest(false, repository)+ countCalls := 0++ result, err := service.CheckAdditional(context.Background(), "user-id", "Contact", 1000, func() (int, error) {+ countCalls+++ return 200, nil+ })++ require.NoError(t, err)+ assert.True(t, result.Allowed)+ assert.Zero(t, repository.loadCalls)+ assert.Zero(t, countCalls)+}++func TestEntitlementService_CheckAdditional_UsesSubscriptionLimitForContactBatch(t *testing.T) {+ tests := []struct {+ name string+ subscriptionName entities.SubscriptionName+ currentCount int+ additionalCount int+ allowed bool+ }{+ {+ name: "free user can reach 200 contacts",+ subscriptionName: entities.SubscriptionNameFree,+ currentCount: 199,+ additionalCount: 1,+ allowed: true,+ },+ {+ name: "free user cannot exceed 200 contacts",+ subscriptionName: entities.SubscriptionNameFree,+ currentCount: 199,+ additionalCount: 2,+ allowed: false,+ },+ {+ name: "pro user can reach 5000 contacts",+ subscriptionName: entities.SubscriptionNameProMonthly,+ currentCount: 4999,+ additionalCount: 1,+ allowed: true,+ },+ {+ name: "pro user cannot exceed 5000 contacts",+ subscriptionName: entities.SubscriptionNameProMonthly,+ currentCount: 4999,+ additionalCount: 2,+ allowed: false,+ },+ }++ for _, test := range tests {+ t.Run(test.name, func(t *testing.T) {+ repository := &entitlementUserRepository{+ user: &entities.User{SubscriptionName: test.subscriptionName},+ }+ service := newEntitlementServiceForTest(true, repository)++ result, err := service.CheckAdditional(context.Background(), "user-id", "Contact", test.additionalCount, func() (int, error) {+ return test.currentCount, nil+ })++ require.NoError(t, err)+ assert.Equal(t, test.allowed, result.Allowed)+ if !test.allowed {+ assert.Contains(t, result.Message, "more than ["+strconv.FormatUint(uint64(test.subscriptionName.Limit()), 10)+"]")+ assert.Contains(t, result.Message, "Upgrade your plan")+ }+ })+ }+}diff --git a/api/pkg/services/message_thread_service.go b/api/pkg/services/message_thread_service.goindex 532a223e..8431672b 100644--- a/api/pkg/services/message_thread_service.go+++ b/api/pkg/services/message_thread_service.go@@ -15,6 +15,10 @@ import ("github.com/google/uuid")+type contactMapProvider interface {+ GetContactMap(ctx context.Context, userID entities.UserID, phoneNumbers []string) (map[string]*entities.Contact, error)+}+// MessageThreadService is handles message requeststype MessageThreadService struct {service@@ -23,6 +27,7 @@ type MessageThreadService struct {repository repositories.MessageThreadRepositoryphoneRepository repositories.PhoneRepositoryeventDispatcher *EventDispatcher+ contactService contactMapProvider}// NewMessageThreadService creates a new MessageThreadService@@ -32,6 +37,7 @@ func NewMessageThreadService(repository repositories.MessageThreadRepository,phoneRepository repositories.PhoneRepository,eventDispatcher *EventDispatcher,+ contactService contactMapProvider,) (s *MessageThreadService) {return &MessageThreadService{logger: logger.WithService(fmt.Sprintf("%T", s)),@@ -39,6 +45,7 @@ func NewMessageThreadService(eventDispatcher: eventDispatcher,repository: repository,phoneRepository: phoneRepository,+ contactService: contactService,}}@@ -265,23 +272,40 @@ func (service *MessageThreadService) getColor() string {// MessageThreadGetParams parameters fetching threadstype MessageThreadGetParams struct {repositories.IndexParams- IsArchived bool- UserID entities.UserID- Owner string+ IsArchived bool+ WithContacts bool+ UserID entities.UserID+ Owner string}// GetThreads fetches threads for an ownerfunc (service *MessageThreadService) GetThreads(ctx context.Context, params MessageThreadGetParams) (*[]entities.MessageThread, error) {- ctx, span := service.tracer.Start(ctx)+ ctx, span, ctxLogger := service.tracer.StartWithLogger(ctx, service.logger)defer span.End()- ctxLogger := service.tracer.CtxLogger(service.logger, span)-threads, err := service.repository.Index(ctx, params.UserID, params.Owner, params.IsArchived, params.IndexParams)if err != nil {return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "could not fetch messages threads for params [%+#v]", params))}+ if params.WithContacts && len(*threads) > 0 {+ phoneNumbers := make([]string, 0, len(*threads))+ for index := range *threads {+ phoneNumbers = append(phoneNumbers, (*threads)[index].Contact)+ }++ contactMap, mapErr := service.contactService.GetContactMap(ctx, params.UserID, phoneNumbers)+ if mapErr != nil {+ ctxLogger.Error(service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(mapErr, "cannot build contact map for user [%s]", params.UserID)))+ } else {+ for index := range *threads {+ if contact, ok := contactMap[(*threads)[index].Contact]; ok {+ (*threads)[index].ContactDetails = contact+ }+ }+ }+ }+ctxLogger.Info(fmt.Sprintf("fetched [%d] threads with params [%+#v]", len(*threads), params))return threads, nil}diff --git a/api/pkg/services/message_thread_service_contacts_test.go b/api/pkg/services/message_thread_service_contacts_test.gonew file mode 100644index 00000000..2c021d2f--- /dev/null+++ b/api/pkg/services/message_thread_service_contacts_test.go@@ -0,0 +1,159 @@+package services++import (+ "context"+ "errors"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "go.opentelemetry.io/otel/trace"+)++type messageThreadContactRepositoryStub struct {+ repositories.MessageThreadRepository+ threads []entities.MessageThread+ err error+ calls int+}++func (stub *messageThreadContactRepositoryStub) Index(_ context.Context, _ entities.UserID, _ string, _ bool, _ repositories.IndexParams) (*[]entities.MessageThread, error) {+ stub.calls+++ if stub.err != nil {+ return nil, stub.err+ }+ threads := make([]entities.MessageThread, len(stub.threads))+ copy(threads, stub.threads)+ return &threads, nil+}++type messageThreadContactProviderStub struct {+ contacts map[string]*entities.Contact+ err error+ calls int+ userID entities.UserID+ numbers []string+}++func (stub *messageThreadContactProviderStub) GetContactMap(_ context.Context, userID entities.UserID, phoneNumbers []string) (map[string]*entities.Contact, error) {+ stub.calls+++ stub.userID = userID+ stub.numbers = append([]string{}, phoneNumbers...)+ return stub.contacts, stub.err+}++type messageThreadContactLogger struct {+ errors []error+}++var _ telemetry.Logger = (*messageThreadContactLogger)(nil)++func (logger *messageThreadContactLogger) Error(err error) {+ logger.errors = append(logger.errors, err)+}++func (logger *messageThreadContactLogger) WithService(string) telemetry.Logger { return logger }++func (logger *messageThreadContactLogger) WithString(string, string) telemetry.Logger { return logger }++func (logger *messageThreadContactLogger) WithSpan(trace.SpanContext) telemetry.Logger { return logger }+func (logger *messageThreadContactLogger) Trace(string) {}+func (logger *messageThreadContactLogger) Info(string) {}+func (logger *messageThreadContactLogger) Warn(error) {}+func (logger *messageThreadContactLogger) Debug(string) {}+func (logger *messageThreadContactLogger) Fatal(error) {}+func (logger *messageThreadContactLogger) Printf(string, ...interface{}) {}++func newMessageThreadContactServiceForTest(repository repositories.MessageThreadRepository, provider contactMapProvider, logger telemetry.Logger) *MessageThreadService {+ if logger == nil {+ logger = &noopLogger{}+ }+ tracer := telemetry.NewOtelLogger("test", logger)+ return NewMessageThreadService(logger, tracer, repository, nil, nil, provider)+}++func TestGetThreads_SkipsContactLookupWhenFlagOff(t *testing.T) {+ repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550199"}}}+ provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{+ "+18005550199": {Name: "Alice"},+ }}+ service := newMessageThreadContactServiceForTest(repository, provider, nil)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: false})++ require.NoError(t, err)+ require.Len(t, *threads, 1)+ assert.Nil(t, (*threads)[0].ContactDetails)+ assert.Equal(t, 0, provider.calls)+}++func TestGetThreads_AttachesContactDetailsWhenFlagOn(t *testing.T) {+ alice := &entities.Contact{ID: uuid.New(), Name: "Alice", PhoneNumbers: []string{"+18005550199"}}+ repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{+ {Contact: "+18005550199"},+ {Contact: "+18005550100"},+ }}+ provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{+ "+18005550199": alice,+ }}+ service := newMessageThreadContactServiceForTest(repository, provider, nil)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})++ require.NoError(t, err)+ require.Len(t, *threads, 2)+ assert.Equal(t, 1, provider.calls)+ assert.Equal(t, entities.UserID("user-id"), provider.userID)+ assert.Equal(t, []string{"+18005550199", "+18005550100"}, provider.numbers)+ require.NotNil(t, (*threads)[0].ContactDetails)+ assert.Same(t, alice, (*threads)[0].ContactDetails)+ assert.Equal(t, "Alice", (*threads)[0].ContactDetails.Name)+ assert.Nil(t, (*threads)[1].ContactDetails)+}++func TestGetThreads_SkipsContactLookupWhenNoThreads(t *testing.T) {+ repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{}}+ provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{}}+ service := newMessageThreadContactServiceForTest(repository, provider, nil)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})++ require.NoError(t, err)+ require.Empty(t, *threads)+ assert.Equal(t, 0, provider.calls)+}++func TestGetThreads_LogsContactMapErrorAndReturnsThreads(t *testing.T) {+ repository := &messageThreadContactRepositoryStub{threads: []entities.MessageThread{{Contact: "+18005550199"}}}+ provider := &messageThreadContactProviderStub{err: errors.New("contacts unavailable")}+ logger := &messageThreadContactLogger{}+ service := newMessageThreadContactServiceForTest(repository, provider, logger)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})++ require.NoError(t, err)+ require.Len(t, *threads, 1)+ assert.Nil(t, (*threads)[0].ContactDetails)+ assert.Equal(t, 1, provider.calls)+ require.Len(t, logger.errors, 1)+ assert.ErrorContains(t, logger.errors[0], "cannot build contact map")+}++func TestGetThreads_DoesNotLookupContactsWhenRepositoryFails(t *testing.T) {+ repository := &messageThreadContactRepositoryStub{err: stacktrace.NewError("repository failed")}+ provider := &messageThreadContactProviderStub{contacts: map[string]*entities.Contact{+ "+18005550199": {Name: "Alice"},+ }}+ service := newMessageThreadContactServiceForTest(repository, provider, nil)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: entities.UserID("user-id"), WithContacts: true})++ require.Error(t, err)+ assert.Nil(t, threads)+ assert.Equal(t, 0, provider.calls)+}diff --git a/api/pkg/services/message_thread_service_test.go b/api/pkg/services/message_thread_service_test.goindex 8cc8bdcb..44a3bcfd 100644--- a/api/pkg/services/message_thread_service_test.go+++ b/api/pkg/services/message_thread_service_test.go@@ -72,7 +72,7 @@ func (stub *messageThreadRepositoryStub) DeleteAllForUser(context.Context, entitfunc newMessageThreadServiceForTest(repository repositories.MessageThreadRepository) *MessageThreadService {logger := &noopLogger{}tracer := telemetry.NewOtelLogger("test", logger)- return NewMessageThreadService(logger, tracer, repository, nil, nil)+ return NewMessageThreadService(logger, tracer, repository, nil, nil, nil)}func TestUpdateThreadPassesUnreadWatermarkForInboundActivity(t *testing.T) {diff --git a/api/pkg/validators/bulk_message_handler_validator.go b/api/pkg/validators/bulk_message_handler_validator.goindex 588407ac..956c1489 100644--- a/api/pkg/validators/bulk_message_handler_validator.go+++ b/api/pkg/validators/bulk_message_handler_validator.go@@ -12,7 +12,6 @@ import ("github.com/xuri/excelize/v2"- "github.com/NdoleStudio/httpsms/pkg/cache""github.com/NdoleStudio/httpsms/pkg/entities""github.com/NdoleStudio/httpsms/pkg/repositories""github.com/NdoleStudio/httpsms/pkg/requests"@@ -31,7 +30,6 @@ type BulkMessageHandlerValidator struct {userService *services.UserServicelogger telemetry.Loggertracer telemetry.Tracer- cache cache.Cache}// NewBulkMessageHandlerValidator creates a new handlers.BulkMessageHandlerValidator validator@@ -40,14 +38,12 @@ func NewBulkMessageHandlerValidator(tracer telemetry.Tracer,phoneService *services.PhoneService,userService *services.UserService,- appCache cache.Cache,) (v *BulkMessageHandlerValidator) {return &BulkMessageHandlerValidator{logger: logger.WithService(fmt.Sprintf("%T", v)),tracer: tracer,userService: userService,phoneService: phoneService,- cache: appCache,}}diff --git a/api/pkg/validators/contact_handler_validator.go b/api/pkg/validators/contact_handler_validator.gonew file mode 100644index 00000000..f3256160--- /dev/null+++ b/api/pkg/validators/contact_handler_validator.go@@ -0,0 +1,359 @@+package validators++import (+ "bytes"+ "context"+ "encoding/csv"+ "fmt"+ "io"+ "mime/multipart"+ "net/mail"+ "net/url"+ "path/filepath"+ "strconv"+ "strings"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/nyaruka/phonenumbers"+ "github.com/thedevsaddam/govalidator"+)++const (+ maxContactBatch = 1000+ maxContactUploadBytes = 500 * 1024+ contactUploadDocumentKey = "document"+ contactUploadContactsKey = "contacts"+ contactCSVColumnName = "Name"+ contactCSVColumnEmails = "Emails"+ contactCSVColumnPhones = "PhoneNumbers"+ contactCSVContentType = "text/csv"+ contactCSVContentTypeAlt = "application/csv"+ contactCSVContentTypeBin = "application/octet-stream"+ contactCSVContentTypeXls = "application/vnd.ms-excel"+)++// ContactHandlerValidator validates models used in handlers.ContactHandler+type ContactHandlerValidator struct {+ validator+ logger telemetry.Logger+ tracer telemetry.Tracer+}++// NewContactHandlerValidator creates a new handlers.ContactHandler validator+func NewContactHandlerValidator(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+) (v *ContactHandlerValidator) {+ return &ContactHandlerValidator{+ logger: logger.WithService(fmt.Sprintf("%T", v)),+ tracer: tracer,+ }+}++// ValidateStore validates a contact create request.+func (validator *ContactHandlerValidator) ValidateStore(_ context.Context, request requests.ContactStoreRequest) url.Values {+ result := url.Values{}++ if len(request.Contacts) == 0 {+ result.Add(contactUploadContactsKey, "You must provide at least one contact.")+ return result+ }++ if len(request.Contacts) > maxContactBatch {+ result.Add(contactUploadContactsKey, fmt.Sprintf("You cannot create more than %d contacts in one request.", maxContactBatch))+ return result+ }++ for index, item := range request.Contacts {+ validator.validateItem(result, contactUploadContactsKey, "Contact", index+1, item)+ }++ return result+}++// ValidateUpdate validates a contact update request.+func (validator *ContactHandlerValidator) ValidateUpdate(_ context.Context, request requests.ContactUpdateRequest) url.Values {+ result := url.Values{}+ validator.validateItem(result, contactUploadContactsKey, "Contact", 1, requests.ContactItem{+ Name: request.Name,+ Emails: request.Emails,+ PhoneNumbers: request.PhoneNumbers,+ Properties: request.Properties,+ })+ return result+}++// ValidateIndex validates a contact index request.+func (validator *ContactHandlerValidator) ValidateIndex(_ context.Context, request requests.ContactIndex) url.Values {+ result := govalidator.New(govalidator.Options{+ Data: &request,+ Rules: govalidator.MapData{+ "limit": []string{"required", "numeric"},+ "skip": []string{"required", "numeric"},+ "query": []string{"max:100"},+ "sort_by": []string{"in:name,updated_at"},+ },+ }).ValidateStruct()++ if limit, err := strconv.Atoi(request.Limit); request.Limit != "" && err == nil {+ if limit < 1 || limit > 100 {+ result.Add("limit", "The limit must be between 1 and 100.")+ }+ }++ if skip, err := strconv.Atoi(request.Skip); request.Skip != "" && err == nil {+ if skip < 0 {+ result.Add("skip", "The skip must be greater than or equal to 0.")+ }+ }++ return result+}++// ValidateUpload parses and validates a CSV contacts upload.+func (validator *ContactHandlerValidator) ValidateUpload(ctx context.Context, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values) {+ _, span, ctxLogger := validator.tracer.StartWithLogger(ctx, validator.logger)+ defer span.End()++ result := url.Values{}+ if header == nil {+ result.Add(contactUploadDocumentKey, "The CSV file is required.")+ return nil, result+ }++ if !isContactCSVFile(header) {+ ctxLogger.Error(stacktrace.NewErrorf("cannot parse file [%s] for user [%s] with content type [%s]", header.Filename, userID, header.Header.Get("Content-Type")))+ result.Add(contactUploadDocumentKey, fmt.Sprintf("The file [%s] is not a valid CSV file. Only CSV files are supported.", header.Filename))+ return nil, result+ }++ content, errors := validator.parseContactUploadBytes(ctxLogger, userID, header)+ if len(errors) != 0 {+ return nil, errors+ }++ rows, errors := validator.parseContactCSV(ctxLogger, userID, header.Filename, content)+ if len(errors) != 0 {+ return nil, errors+ }++ if len(rows) > maxContactBatch {+ result.Add(contactUploadDocumentKey, fmt.Sprintf("The uploaded file must contain no more than %d records.", maxContactBatch))+ return nil, result+ }++ items := make([]requests.ContactItem, 0, len(rows))+ for _, row := range rows {+ // Sanitize each row exactly like the JSON create path (SanitizeContactItem)+ // before validating it, so both entry points accept and normalize the same+ // phone/email formats. Row-indexed error messages are preserved because the+ // row number is still passed to validateItem.+ item := requests.SanitizeContactItem(requests.ContactItem{+ Name: row.values[contactCSVColumnName],+ Emails: splitContactMultiValue(row.values[contactCSVColumnEmails]),+ PhoneNumbers: splitContactMultiValue(row.values[contactCSVColumnPhones]),+ })+ items = append(items, item)+ validator.validateItem(result, contactUploadDocumentKey, "Row", row.number, item)+ }++ if len(items) == 0 {+ result.Add(contactUploadDocumentKey, "The uploaded file must contain at least one contact.")+ }++ return items, result+}++func (validator *ContactHandlerValidator) validateItem(result url.Values, key string, label string, index int, item requests.ContactItem) {+ prefix := fmt.Sprintf("%s [%d]", label, index)++ if strings.TrimSpace(item.Name) == "" {+ result.Add(key, fmt.Sprintf("%s: The name is required.", prefix))+ }++ if !hasNonEmptyValue(item.PhoneNumbers) {+ result.Add(key, fmt.Sprintf("%s: At least one phone number is required.", prefix))+ }++ for _, number := range item.PhoneNumbers {+ cleanNumber := strings.TrimSpace(number)+ if cleanNumber == "" {+ result.Add(key, fmt.Sprintf("%s: The phone number is required.", prefix))+ continue+ }++ parsed, err := phonenumbers.Parse(cleanNumber, phonenumbers.UNKNOWN_REGION)+ if err != nil || !phonenumbers.IsValidNumber(parsed) {+ result.Add(key, fmt.Sprintf("%s: The phone number [%s] is not a valid E.164 phone number.", prefix, cleanNumber))+ }+ }++ for _, email := range item.Emails {+ cleanEmail := strings.TrimSpace(email)+ if cleanEmail == "" {+ result.Add(key, fmt.Sprintf("%s: The email is not a valid email address.", prefix))+ continue+ }++ address, err := mail.ParseAddress(cleanEmail)+ if err != nil || address.Address != cleanEmail {+ result.Add(key, fmt.Sprintf("%s: The email [%s] is not a valid email address.", prefix, cleanEmail))+ }+ }+}++func (validator *ContactHandlerValidator) parseContactUploadBytes(ctxLogger telemetry.Logger, userID entities.UserID, header *multipart.FileHeader) ([]byte, url.Values) {+ result := url.Values{}++ if header.Size > maxContactUploadBytes {+ result.Add(contactUploadDocumentKey, "The CSV file must be less than or equal to 500 KB.")+ return nil, result+ }++ file, err := header.Open()+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot open file [%s] for reading for user [%s]", header.Filename, userID))+ result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot open the uploaded file [%s].", header.Filename))+ return nil, result+ }+ defer func() {+ if closeErr := file.Close(); closeErr != nil {+ ctxLogger.Error(stacktrace.Propagatef(closeErr, "cannot close file [%s] for user [%s]", header.Filename, userID))+ }+ }()++ content, err := io.ReadAll(io.LimitReader(file, maxContactUploadBytes+1))+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot read file [%s] for user [%s]", header.Filename, userID))+ result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot read the uploaded file [%s].", header.Filename))+ return nil, result+ }++ if len(content) > maxContactUploadBytes {+ result.Add(contactUploadDocumentKey, "The CSV file must be less than or equal to 500 KB.")+ return nil, result+ }++ return content, result+}++type contactCSVRow struct {+ number int+ values map[string]string+}++func (validator *ContactHandlerValidator) parseContactCSV(ctxLogger telemetry.Logger, userID entities.UserID, filename string, content []byte) ([]contactCSVRow, url.Values) {+ result := url.Values{}+ reader := csv.NewReader(bytes.NewReader(content))+ reader.TrimLeadingSpace = true++ headers, err := reader.Read()+ if err == io.EOF {+ result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. The file is empty.", filename))+ return nil, result+ }+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot read CSV header from file [%s] for user [%s]", filename, userID))+ result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", filename))+ return nil, result+ }++ columnIndexes, ok := contactCSVColumnIndexes(headers)+ if !ok {+ result.Add(contactUploadDocumentKey, "The uploaded CSV file must contain the columns [Name, Emails, PhoneNumbers].")+ return nil, result+ }++ reader.FieldsPerRecord = len(headers)++ var rows []contactCSVRow+ for rowNumber := 2; ; rowNumber++ {+ record, readErr := reader.Read()+ if readErr == io.EOF {+ break+ }+ if readErr != nil {+ ctxLogger.Error(stacktrace.Propagatef(readErr, "cannot read CSV row [%d] from file [%s] for user [%s]", rowNumber, filename, userID))+ result.Add(contactUploadDocumentKey, fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", filename))+ return nil, result+ }++ row := contactCSVRow{+ number: rowNumber,+ values: map[string]string{+ contactCSVColumnName: record[columnIndexes[contactCSVColumnName]],+ contactCSVColumnEmails: record[columnIndexes[contactCSVColumnEmails]],+ contactCSVColumnPhones: record[columnIndexes[contactCSVColumnPhones]],+ },+ }+ rows = append(rows, row)+ if len(rows) > maxContactBatch {+ return rows, result+ }+ }++ return rows, result+}++func contactCSVColumnIndexes(headers []string) (map[string]int, bool) {+ required := []string{contactCSVColumnName, contactCSVColumnEmails, contactCSVColumnPhones}+ indexes := map[string]int{}+ for index, header := range headers {+ indexes[strings.TrimSpace(header)] = index+ }++ for _, column := range required {+ if _, ok := indexes[column]; !ok {+ return nil, false+ }+ }++ return indexes, true+}++func isContactCSVFile(header *multipart.FileHeader) bool {+ if strings.ToLower(filepath.Ext(header.Filename)) != ".csv" {+ return false+ }++ contentType := strings.ToLower(strings.TrimSpace(header.Header.Get("Content-Type")))+ if index := strings.Index(contentType, ";"); index >= 0 {+ contentType = strings.TrimSpace(contentType[:index])+ }++ return contentType == "" ||+ contentType == contactCSVContentType ||+ contentType == contactCSVContentTypeAlt ||+ contentType == contactCSVContentTypeBin ||+ contentType == contactCSVContentTypeXls+}++func splitContactMultiValue(value string) []string {+ if strings.TrimSpace(value) == "" {+ return nil+ }++ var result []string+ for _, item := range strings.FieldsFunc(value, func(r rune) bool {+ return r == ',' || r == ';'+ }) {+ item = strings.TrimSpace(item)+ if item != "" {+ result = append(result, item)+ }+ }++ return result+}++func hasNonEmptyValue(values []string) bool {+ for _, value := range values {+ if strings.TrimSpace(value) != "" {+ return true+ }+ }+ return false+}diff --git a/api/pkg/validators/contact_handler_validator_test.go b/api/pkg/validators/contact_handler_validator_test.gonew file mode 100644index 00000000..bb145dbf--- /dev/null+++ b/api/pkg/validators/contact_handler_validator_test.go@@ -0,0 +1,435 @@+package validators++import (+ "bytes"+ "context"+ "fmt"+ "mime/multipart"+ "net/http"+ "net/http/httptest"+ "net/textproto"+ "strings"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "go.opentelemetry.io/otel/trace"+)++func newContactValidator() *ContactHandlerValidator {+ return &ContactHandlerValidator{}+}++func newContactUploadValidator() *ContactHandlerValidator {+ logger := &contactValidatorNoopLogger{}+ return NewContactHandlerValidator(logger, telemetry.NewOtelLogger("test", logger))+}++func TestContactValidator_ValidateStore_ValidOneAndMany(t *testing.T) {+ validator := newContactValidator()++ tests := []struct {+ name string+ request requests.ContactStoreRequest+ }{+ {+ name: "one contact",+ request: requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ Emails: []string{"[email protected]"},+ }}},+ },+ {+ name: "many contacts",+ request: requests.ContactStoreRequest{Contacts: []requests.ContactItem{+ {+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199", "+18005550100"},+ Emails: []string{"[email protected]", "[email protected]"},+ },+ {+ Name: "Bob",+ PhoneNumbers: []string{"+14155552671"},+ },+ }},+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ errs := validator.ValidateStore(context.Background(), tt.request)++ assert.Empty(t, errs)+ })+ }+}++func TestContactValidator_ValidateStore_MissingName(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ PhoneNumbers: []string{"+18005550199"},+ }}})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "Contact [1]")+ assert.Contains(t, errs["contacts"][0], "name")+}++func TestContactValidator_ValidateStore_NoPhoneNumber(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ }}})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "Contact [1]")+ assert.Contains(t, errs["contacts"][0], "phone number")+}++func TestContactValidator_ValidateStore_EmptyBatch(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "at least one contact")+}++func TestContactValidator_ValidateStore_InvalidPhoneNumber(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"not-a-number"},+ }}})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "Contact [1]")+ assert.Contains(t, errs["contacts"][0], "not-a-number")+}++func TestContactValidator_ValidateStore_InvalidEmail(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ Emails: []string{"not-an-email"},+ }}})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "Contact [1]")+ assert.Contains(t, errs["contacts"][0], "not-an-email")+}++func TestContactValidator_ValidateStore_RejectsEmptyPhoneAndEmailElements(t *testing.T) {+ validator := newContactValidator()++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199", " "},+ Emails: []string{" "},+ }}})++ contactsErrors := strings.Join(errs["contacts"], "\n")+ assert.Contains(t, contactsErrors, "phone number")+ assert.Contains(t, contactsErrors, "email")+}++func TestContactValidator_ValidateStore_RejectsMoreThan1000Contacts(t *testing.T) {+ validator := newContactValidator()+ contacts := make([]requests.ContactItem, 1001)+ for index := range contacts {+ contacts[index] = requests.ContactItem{Name: "Alice", PhoneNumbers: []string{"+18005550199"}}+ }++ errs := validator.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: contacts})++ require.NotEmpty(t, errs.Get("contacts"))+ assert.Contains(t, errs["contacts"][0], "1000")+}++func TestContactValidator_ValidateUpdate_ValidAndInvalid(t *testing.T) {+ validator := newContactValidator()++ validErrs := validator.ValidateUpdate(context.Background(), requests.ContactUpdateRequest{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ Emails: []string{"[email protected]"},+ })+ assert.Empty(t, validErrs)++ invalidErrs := validator.ValidateUpdate(context.Background(), requests.ContactUpdateRequest{+ Name: "",+ PhoneNumbers: []string{"not-a-number"},+ Emails: []string{"not-an-email"},+ })+ assert.NotEmpty(t, invalidErrs.Get("contacts"))+}++func TestContactValidator_ValidateIndex(t *testing.T) {+ validator := newContactValidator()++ validErrs := validator.ValidateIndex(context.Background(), requests.ContactIndex{+ Skip: "0",+ Limit: "100",+ Query: strings.Repeat("a", 100),+ SortBy: "updated_at",+ })+ assert.Empty(t, validErrs)++ tests := []struct {+ name string+ request requests.ContactIndex+ key string+ }{+ {name: "limit too low", request: requests.ContactIndex{Skip: "0", Limit: "0"}, key: "limit"},+ {name: "limit too high", request: requests.ContactIndex{Skip: "0", Limit: "101"}, key: "limit"},+ {name: "skip negative", request: requests.ContactIndex{Skip: "-1", Limit: "20"}, key: "skip"},+ {name: "query too long", request: requests.ContactIndex{Skip: "0", Limit: "20", Query: strings.Repeat("a", 101)}, key: "query"},+ {name: "unsupported sort field", request: requests.ContactIndex{Skip: "0", Limit: "20", SortBy: "created_at"}, key: "sort_by"},+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ errs := validator.ValidateIndex(context.Background(), tt.request)++ assert.NotEmpty(t, errs.Get(tt.key))+ })+ }+}++func TestContactValidator_ValidateUpload_ParsesValidCSVWithQuotedMultiValueCells(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{+ "Name,Emails,PhoneNumbers",+ `Alice,"[email protected],[email protected]","+18005550199,+18005550100"`,+ `Bob,[email protected];[email protected],+14155552671;+14155552672`,+ }, "\n"))++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Empty(t, errs)+ require.Len(t, items, 2)+ assert.Equal(t, "Alice", items[0].Name)+ assert.Equal(t, []string{"[email protected]", "[email protected]"}, items[0].Emails)+ assert.Equal(t, []string{"+18005550199", "+18005550100"}, items[0].PhoneNumbers)+ assert.Equal(t, "Bob", items[1].Name)+ assert.Equal(t, []string{"[email protected]", "[email protected]"}, items[1].Emails)+ assert.Equal(t, []string{"+14155552671", "+14155552672"}, items[1].PhoneNumbers)+}++func TestContactValidator_ValidateUpload_RejectsNonCSVExtensionAndMIME(t *testing.T) {+ validator := newContactUploadValidator()++ tests := []struct {+ name string+ filename string+ contentType string+ }{+ {name: "xlsx extension", filename: "contacts.xlsx", contentType: "text/csv"},+ {name: "xlsx mime", filename: "contacts.csv", contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ header := multipartFileHeader(t, tt.filename, tt.contentType, "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ assert.NotEmpty(t, errs.Get("document"))+ })+ }+}++func TestContactValidator_ValidateUpload_AcceptsCSVWithOctetStreamMIME(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "application/octet-stream", "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Empty(t, errs)+ require.Len(t, items, 1)+ assert.Equal(t, "Alice", items[0].Name)+}++func TestContactValidator_ValidateUpload_AcceptsCSVWithVndMsExcelMIME(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "application/vnd.ms-excel", "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Empty(t, errs)+ require.Len(t, items, 1)+ assert.Equal(t, "Alice", items[0].Name)+}++func TestContactValidator_ValidateUpload_AcceptsCSVWithEmptyMIME(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "", "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Empty(t, errs)+ require.Len(t, items, 1)+ assert.Equal(t, "Alice", items[0].Name)+}++func TestContactValidator_ValidateUpload_RejectsXlsxDespiteSpreadsheetMIME(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.xlsx", "application/vnd.ms-excel", "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "not a valid CSV file")+}++func TestContactValidator_ValidateUpload_RejectsCSVWithUnrelatedMIME(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "image/png", "Name,Emails,PhoneNumbers\nAlice,[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "not a valid CSV file")+}++func TestContactValidator_ValidateUpload_RejectsOversizedFile(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Repeat("a", 500*1024+1))++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "500 KB")+}++func TestContactValidator_ValidateUpload_RejectsMalformedCSV(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "text/csv", "Name,Emails,PhoneNumbers\nAlice,\"[email protected],+18005550199")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "Cannot parse")+}++func TestContactValidator_ValidateUpload_RejectsMissingRequiredColumns(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "text/csv", "Name,Emails\nAlice,[email protected]")++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "Name, Emails, PhoneNumbers")+}++func TestContactValidator_ValidateUpload_RejectsMoreThan1000Rows(t *testing.T) {+ validator := newContactUploadValidator()+ rows := []string{"Name,Emails,PhoneNumbers"}+ for range 1001 {+ rows = append(rows, "Alice,[email protected],+18005550199")+ }+ header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join(rows, "\n"))++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ assert.Nil(t, items)+ require.NotEmpty(t, errs.Get("document"))+ assert.Contains(t, errs["document"][0], "1000")+}++func TestContactValidator_ValidateUpload_ReturnsRowIndexedValidationErrors(t *testing.T) {+ validator := newContactUploadValidator()+ header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{+ "Name,Emails,PhoneNumbers",+ ",[email protected],+18005550199",+ "Alice,,",+ "Bob,not-an-email,not-a-number",+ }, "\n"))++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Len(t, items, 3)+ documentErrors := strings.Join(errs["document"], "\n")+ assert.Contains(t, documentErrors, "Row [2]")+ assert.Contains(t, documentErrors, "Row [3]")+ assert.Contains(t, documentErrors, "Row [4]")+ assert.Contains(t, documentErrors, "not-an-email")+ assert.Contains(t, documentErrors, "not-a-number")+}++func TestContactValidator_ValidateUpload_SanitizesItemsLikeJSONBeforeValidation(t *testing.T) {+ validator := newContactUploadValidator()+ // The phone number lacks a leading "+" and the email has mixed case and+ // surrounding whitespace. The JSON create path sanitizes these before+ // validation, so the CSV path must accept and normalize them identically.+ header := multipartFileHeader(t, "contacts.csv", "text/csv", strings.Join([]string{+ "Name,Emails,PhoneNumbers",+ "Alice, [email protected] ,18005550199",+ }, "\n"))++ items, errs := validator.ValidateUpload(context.Background(), entities.UserID("user-1"), header)++ require.Empty(t, errs, "sanitized CSV rows must pass validation like the JSON path")+ require.Len(t, items, 1)+ assert.Equal(t, "Alice", items[0].Name)+ assert.Equal(t, []string{"+18005550199"}, items[0].PhoneNumbers)+ assert.Equal(t, []string{"[email protected]"}, items[0].Emails)+}++func multipartFileHeader(t *testing.T, filename string, contentType string, content string) *multipart.FileHeader {+ t.Helper()++ var body bytes.Buffer+ writer := multipart.NewWriter(&body)+ header := textproto.MIMEHeader{}+ header.Set("Content-Disposition", fmt.Sprintf(`form-data; name="document"; filename="%s"`, filename))+ header.Set("Content-Type", contentType)++ part, err := writer.CreatePart(header)+ require.NoError(t, err)+ _, err = part.Write([]byte(content))+ require.NoError(t, err)+ require.NoError(t, writer.Close())++ request := httptest.NewRequest(http.MethodPost, "/", &body)+ request.Header.Set("Content-Type", writer.FormDataContentType())+ require.NoError(t, request.ParseMultipartForm(int64(body.Len()+1024)))+ files := request.MultipartForm.File["document"]+ require.Len(t, files, 1)++ return files[0]+}++type contactValidatorNoopLogger struct{}++var _ telemetry.Logger = (*contactValidatorNoopLogger)(nil)++func (logger *contactValidatorNoopLogger) Error(_ error) {}+func (logger *contactValidatorNoopLogger) WithService(_ string) telemetry.Logger { return logger }++func (logger *contactValidatorNoopLogger) WithString(_, _ string) telemetry.Logger { return logger }++func (logger *contactValidatorNoopLogger) WithSpan(_ trace.SpanContext) telemetry.Logger {+ return logger+}+func (logger *contactValidatorNoopLogger) Trace(_ string) {}+func (logger *contactValidatorNoopLogger) Info(_ string) {}+func (logger *contactValidatorNoopLogger) Warn(_ error) {}+func (logger *contactValidatorNoopLogger) Debug(_ string) {}+func (logger *contactValidatorNoopLogger) Fatal(_ error) {}+func (logger *contactValidatorNoopLogger) Printf(_ string, _ ...interface{}) {}diff --git a/api/pkg/validators/message_handler_validator.go b/api/pkg/validators/message_handler_validator.goindex d4da9e10..f14575fa 100644--- a/api/pkg/validators/message_handler_validator.go+++ b/api/pkg/validators/message_handler_validator.go@@ -36,14 +36,12 @@ func NewMessageHandlerValidator(tracer telemetry.Tracer,phoneService *services.PhoneService,tokenValidator *TurnstileTokenValidator,- appCache cache.Cache,) (v *MessageHandlerValidator) {return &MessageHandlerValidator{logger: logger.WithService(fmt.Sprintf("%T", v)),tracer: tracer,phoneService: phoneService,tokenValidator: tokenValidator,- cache: appCache,}}diff --git a/docs/superpowers/plans/2026-07-19-contacts-feature.md b/docs/superpowers/plans/2026-07-19-contacts-feature.mdnew file mode 100644index 00000000..8a72fe40--- /dev/null+++ b/docs/superpowers/plans/2026-07-19-contacts-feature.md@@ -0,0 +1,3025 @@+# Contacts Feature Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Add a Contacts feature (name, emails, phone numbers, free-form properties) with full CRUD + CSV import, and display the resolved contact name instead of the raw phone number on the threads page, using as few DB queries as possible.++**Architecture:** New `Contact` entity + layered backend (handler → service → repository → validator → requests/responses) mirroring existing patterns. Thread-name resolution is opt-in per request and served from a per-user `phone_number → *Contact` map cached in `cache.Cache`, so the common path adds zero DB queries and a name change is a single-row `UPDATE` + cache invalidation. Frontend adds a Pinia store and a Plunk-style Contacts page (Nuxt 4 SPA).++**Tech Stack:** Go (Fiber v3, GORM v1.31.2, lib/pq, nyaruka/phonenumbers, jszwec/csvutil), Nuxt 4 + Pinia + Vuetify 4, Swagger (`swag`), swagger-typescript-api.++## Global Constraints++- Source of truth: `docs/superpowers/specs/2026-07-19-contacts-feature-design.md`. Follow it exactly.+- Run Go tests with `go test -vet=off ./...` from `api/` (Go 1.26 vet rejects the repo's `stacktrace.Propagate(err, fmt.Sprintf(...))` pattern).+- Wrap all Go errors with `github.com/NdoleStudio/stacktrace` (`Propagatef` / `PropagateWithCodef`) — never return bare errors.+- All GORM queries use `repository.db.WithContext(ctx)`. No raw SQL.+- Register Fiber routes via the `h.register(router, fiber.MethodX, path, middlewares, route)` helper (Fiber v3), not `Get`/`Post` directly.+- Contacts are global to the user account. **No** uniqueness constraint on phone numbers; **no** `contact_phone_numbers` lookup table.+- On phone-number collision across contacts, the **most recently updated** contact wins for display.+- Thread-name resolution is **opt-in** via `?contacts=true` (default off).+- Create endpoint accepts one or many; batch capped at **≤ 1000** contacts; cache invalidated **once** after the batch commits.+- CSV import is **CSV only** — Excel/XLSX is not supported for contacts. Max 500 KB, ≤ 1000 rows.+- `pq.StringArray` with `gorm:"type:text[]" swaggertype:"array,string"` for array fields (convention from `phone_api_key.go`/`webhook.go`).+- Web conventions: every `VDialog` has `opacity="0.9"` and a Close button with `color="warning"`; hyperlinks get `text-decoration-none hover:text-decoration-underline`; destructure filters from `useFilters()` in `<script setup>` and use directly in the template; no glowing gradient text off the homepage; Vuetify 4 typography classes (`text-headline-large`, `text-title-large`, `text-display-large`, etc.); in `useApi` `onRequest`, `options.headers` is a `Headers` instance — use `.set()`.+- Regenerate Swagger after API annotation changes: `cd api && swag init --requiredByDefault --parseDependency --parseInternal`.+- Regenerate web API models after Swagger changes: `cd web && pnpm api:models`.++---++## File Structure++Backend (`api/`):+- `pkg/entities/contact.go` — `Contact` entity + `ContactProperties` custom jsonb type (Valuer/Scanner).+- `pkg/entities/contact_test.go` — round-trip tests for `ContactProperties`.+- `pkg/entities/message_thread.go` — add non-persisted `ContactDetails *Contact` field.+- `pkg/repositories/contact_repository.go` — `ContactRepository` interface + param structs.+- `pkg/repositories/gorm_contact_repository.go` — GORM implementation.+- `pkg/repositories/gorm_contact_repository_test.go` — repository tests.+- `pkg/requests/contact_store.go` — create-many request + per-item `ContactItem`.+- `pkg/requests/contact_update.go` — update request.+- `pkg/requests/contact_index.go` — list/search request.+- `pkg/responses/*` — reuse existing generic OK/Created responses (no new file needed).+- `pkg/validators/contact_handler_validator.go` — validates store/update/index + CSV parse.+- `pkg/services/contact_service.go` — CRUD + contact-map build + cache invalidation.+- `pkg/services/contact_service_test.go` — service tests.+- `pkg/handlers/contact_handler.go` — HTTP handlers + `RegisterRoutes`.+- `pkg/services/message_thread_service.go` — extend `GetThreads` to attach `ContactDetails`.+- `pkg/requests/message_thread_index_request.go` — add `Contacts` query param.+- `pkg/di/container.go` — wire repo/service/validator/handler, AutoMigrate, register routes.++Frontend (`web/`):+- `app/stores/contacts.ts` — Pinia store.+- `app/pages/contacts/index.vue` — Plunk-style Contacts page + dialogs.+- `app/stores/threads.ts` — pass `contacts: true`.+- `app/components/MessageThread.vue`, `app/components/MessageThreadHeader.vue` — render resolved name.+- default layout — add Contacts nav link.+- `shared/types/api` — regenerated from Swagger.+- `public/templates/httpsms-contacts.csv` — CSV template.++---++### Task 1: Contact entity + ContactProperties custom type++**Files:**+- Create: `api/pkg/entities/contact.go`+- Create: `api/pkg/entities/contact_test.go`++**Interfaces:**+- Produces: `entities.Contact` struct; `entities.ContactProperties` (`map[string]string`) implementing `driver.Valuer` and `sql.Scanner`.++- [ ] **Step 1: Write the failing test**++Create `api/pkg/entities/contact_test.go`:++```go+package entities++import (+ "testing"++ "github.com/stretchr/testify/assert"+)++func TestContactProperties_ValueScanRoundTrip(t *testing.T) {+ cases := []ContactProperties{+ nil,+ {},+ {"company": "Acme", "role": "CTO"},+ }++ for _, original := range cases {+ value, err := original.Value()+ assert.Nil(t, err)++ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(value))++ if len(original) == 0 {+ assert.Equal(t, 0, len(scanned))+ continue+ }+ assert.Equal(t, original, scanned)+ }+}++func TestContactProperties_ScanFromString(t *testing.T) {+ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(`{"k":"v"}`))+ assert.Equal(t, ContactProperties{"k": "v"}, scanned)+}++func TestContactProperties_ScanNil(t *testing.T) {+ var scanned ContactProperties+ assert.Nil(t, scanned.Scan(nil))+ assert.Equal(t, 0, len(scanned))+}+```++- [ ] **Step 2: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/entities/ -run TestContactProperties`+Expected: FAIL / build error — `Contact`/`ContactProperties` undefined.++- [ ] **Step 3: Write minimal implementation**++Create `api/pkg/entities/contact.go`:++```go+package entities++import (+ "database/sql/driver"+ "encoding/json"+ "fmt"+ "time"++ "github.com/google/uuid"+ "github.com/lib/pq"+)++// ContactProperties is a free-form key/value map persisted as a jsonb column.+type ContactProperties map[string]string++// Value implements driver.Valuer, serializing the map to JSON bytes.+func (p ContactProperties) Value() (driver.Value, error) {+ if p == nil {+ return []byte("{}"), nil+ }+ data, err := json.Marshal(p)+ if err != nil {+ return nil, err+ }+ return data, nil+}++// Scan implements sql.Scanner, deserializing jsonb bytes/string into the map.+func (p *ContactProperties) Scan(src any) error {+ if src == nil {+ *p = ContactProperties{}+ return nil+ }++ var data []byte+ switch value := src.(type) {+ case []byte:+ data = value+ case string:+ data = []byte(value)+ default:+ return fmt.Errorf("unsupported type [%T] for ContactProperties", src)+ }++ if len(data) == 0 {+ *p = ContactProperties{}+ return nil+ }++ result := ContactProperties{}+ if err := json.Unmarshal(data, &result); err != nil {+ return err+ }+ *p = result+ return nil+}++// Contact represents a saved contact belonging to a user.+type Contact struct {+ ID uuid.UUID `json:"id" gorm:"primaryKey;type:uuid;" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`+ UserID UserID `json:"user_id" gorm:"index" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`+ Name string `json:"name" example:"Alice Smith"`+ Emails pq.StringArray `json:"emails" gorm:"type:text[]" swaggertype:"array,string" example:"[email protected]"`+ PhoneNumbers pq.StringArray `json:"phone_numbers" gorm:"type:text[]" swaggertype:"array,string" example:"+18005550199,+18005550100"`+ Properties ContactProperties `json:"properties" gorm:"type:jsonb" swaggertype:"object,string"`+ CreatedAt time.Time `json:"created_at" example:"2022-06-05T14:26:02.302718+03:00"`+ UpdatedAt time.Time `json:"updated_at" example:"2022-06-05T14:26:02.302718+03:00"`+}++// TableName overrides the table name used by Contact.+func (Contact) TableName() string {+ return "contacts"+}+```++- [ ] **Step 4: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/entities/ -run TestContactProperties`+Expected: PASS++- [ ] **Step 5: Commit**++```bash+git add api/pkg/entities/contact.go api/pkg/entities/contact_test.go+git commit -m "feat(api): add Contact entity and ContactProperties jsonb type"+```++---++### Task 2: MessageThread ContactDetails field + AutoMigrate++**Files:**+- Modify: `api/pkg/entities/message_thread.go`+- Modify: `api/pkg/di/container.go` (AutoMigrate block ~L413)++**Interfaces:**+- Produces: `entities.MessageThread.ContactDetails *Contact` (JSON `contact_details`, `gorm:"-"`), `contacts` table auto-migrated.++- [ ] **Step 1: Add the non-persisted field**++In `api/pkg/entities/message_thread.go`, add after the `OrderTimestamp` field inside the `MessageThread` struct:++```go+ // ContactDetails is resolved at read time and never persisted.+ ContactDetails *Contact `json:"contact_details,omitempty" gorm:"-"`+```++- [ ] **Step 2: Register AutoMigrate**++In `api/pkg/di/container.go`, immediately after the `&entities.PhoneAPIKey{}` AutoMigrate block (~L413-415), add:++```go+ if err = db.AutoMigrate(&entities.Contact{}); err != nil {+ container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))+ }+```++- [ ] **Step 3: Build to verify it compiles**++Run: `cd api && go build ./...`+Expected: builds with no errors.++- [ ] **Step 4: Commit**++```bash+git add api/pkg/entities/message_thread.go api/pkg/di/container.go+git commit -m "feat(api): add non-persisted ContactDetails on MessageThread and migrate contacts table"+```++---++### Task 3: ContactRepository interface + GORM implementation++**Files:**+- Create: `api/pkg/repositories/contact_repository.go`+- Create: `api/pkg/repositories/gorm_contact_repository.go`+- Create: `api/pkg/repositories/gorm_contact_repository_test.go`++**Interfaces:**+- Consumes: `entities.Contact`, `repositories.IndexParams`, `repositories.ErrCodeNotFound`.+- Produces: `repositories.ContactRepository` with methods:+ - `Store(ctx context.Context, contacts []*entities.Contact) error`+ - `Update(ctx context.Context, contact *entities.Contact) error`+ - `Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)`+ - `Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)`+ - `FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)` (ordered `updated_at ASC` for tie-break)+ - `Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error`+ - `DeleteAllForUser(ctx context.Context, userID entities.UserID) error`+ - Constructor: `NewGormContactRepository(logger, tracer, db) ContactRepository`++- [ ] **Step 1: Write the interface**++Create `api/pkg/repositories/contact_repository.go`:++```go+package repositories++import (+ "context"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+)++// ContactRepository loads and persists an entities.Contact+type ContactRepository interface {+ // Store one or many new entities.Contact+ Store(ctx context.Context, contacts []*entities.Contact) error++ // Update an existing entities.Contact+ Update(ctx context.Context, contact *entities.Contact) error++ // Load a contact by ID for a user+ Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)++ // Index contacts for a user with optional search+ Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error)++ // FetchAll returns every contact for a user ordered by updated_at ascending+ FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error)++ // Delete a contact by ID for a user+ Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error++ // DeleteAllForUser deletes all contacts for a user+ DeleteAllForUser(ctx context.Context, userID entities.UserID) error+}+```++- [ ] **Step 2: Write the failing test**++Create `api/pkg/repositories/gorm_contact_repository_test.go`. Reuse the SQL-capturing conn-pool mock pattern already defined in `api/pkg/repositories/gorm_message_thread_repository_test.go` (the `messageThreadTestConnPool`, `messageThreadTestLogger`, and the `postgres.New(postgres.Config{Conn: ...})` DryRun setup). Add these focused tests:++```go+package repositories++import (+ "context"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+ "gorm.io/driver/postgres"+ "gorm.io/gorm"+)++func newContactTestRepo(t *testing.T) (ContactRepository, *messageThreadTestConnPool) {+ pool := &messageThreadTestConnPool{}+ db, err := gorm.Open(+ postgres.New(postgres.Config{Conn: pool, WithoutReturning: true}),+ &gorm.Config{DisableAutomaticPing: true},+ )+ require.NoError(t, err)+ logger := &messageThreadTestLogger{}+ return NewGormContactRepository(logger, telemetry.NewOtelLogger("test", logger), db), pool+}++func TestGormContactRepository_Index_FiltersByUserAndQuery(t *testing.T) {+ repo, _ := newContactTestRepo(t)++ _, err := repo.Index(context.Background(), entities.UserID("user-1"), IndexParams{Query: "alice", Limit: 20, Skip: 0})+ assert.Nil(t, err)+}++func TestGormContactRepository_FetchAll_OrdersByUpdatedAtAsc(t *testing.T) {+ repo, _ := newContactTestRepo(t)++ _, err := repo.FetchAll(context.Background(), entities.UserID("user-1"))+ assert.Nil(t, err)+}++func TestGormContactRepository_Store_BuildsContact(t *testing.T) {+ repo, _ := newContactTestRepo(t)++ err := repo.Store(context.Background(), []*entities.Contact{{+ ID: uuid.New(),+ UserID: entities.UserID("user-1"),+ Name: "Alice",+ Emails: pq.StringArray{"[email protected]"},+ PhoneNumbers: pq.StringArray{"+18005550199"},+ }})+ assert.Nil(t, err)+}+```++(The `messageThreadTestConnPool` and `messageThreadTestLogger` types are already defined in `gorm_message_thread_repository_test.go` in the same package, so they are reused directly here.)++- [ ] **Step 3: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/repositories/ -run TestGormContactRepository`+Expected: FAIL / build error — `NewGormContactRepository` undefined.++- [ ] **Step 4: Write the implementation**++Create `api/pkg/repositories/gorm_contact_repository.go`:++```go+package repositories++import (+ "context"+ "errors"+ "fmt"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "gorm.io/gorm"+)++// gormContactRepository is responsible for persisting entities.Contact+type gormContactRepository struct {+ logger telemetry.Logger+ tracer telemetry.Tracer+ db *gorm.DB+}++// NewGormContactRepository creates the GORM version of the ContactRepository+func NewGormContactRepository(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ db *gorm.DB,+) ContactRepository {+ return &gormContactRepository{+ logger: logger.WithService(fmt.Sprintf("%T", &gormContactRepository{})),+ tracer: tracer,+ db: db,+ }+}++func (repository *gormContactRepository) Store(ctx context.Context, contacts []*entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if len(contacts) == 0 {+ return nil+ }++ if err := repository.db.WithContext(ctx).Create(&contacts).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts", len(contacts)))+ }+ return nil+}++func (repository *gormContactRepository) Update(ctx context.Context, contact *entities.Contact) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.db.WithContext(ctx).Save(contact).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact with ID [%s]", contact.ID))+ }+ return nil+}++func (repository *gormContactRepository) Load(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ contact := new(entities.Contact)+ err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Where("id = ?", contactID).+ First(contact).Error+ if errors.Is(err, gorm.ErrRecordNotFound) {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, ErrCodeNotFound, "contact with id [%s] not found for user [%s]", contactID, userID))+ }+ if err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot load contact with id [%s]", contactID))+ }+ return contact, nil+}++func (repository *gormContactRepository) Index(ctx context.Context, userID entities.UserID, params IndexParams) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ query := repository.db.WithContext(ctx).Where("user_id = ?", userID)++ if len(params.Query) > 0 {+ queryPattern := "%" + params.Query + "%"+ query = query.Where(+ repository.db.Where("name ILIKE ?", queryPattern).+ Or("array_to_string(emails, ',') ILIKE ?", queryPattern).+ Or("array_to_string(phone_numbers, ',') ILIKE ?", queryPattern),+ )+ }++ contacts := new([]entities.Contact)+ if err := query.Order("updated_at DESC").Limit(params.Limit).Offset(params.Skip).Find(contacts).Error; err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s]", userID))+ }+ return contacts, nil+}++func (repository *gormContactRepository) FetchAll(ctx context.Context, userID entities.UserID) (*[]entities.Contact, error) {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ contacts := new([]entities.Contact)+ if err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Order("updated_at ASC").+ Find(contacts).Error; err != nil {+ return nil, repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch all contacts for user [%s]", userID))+ }+ return contacts, nil+}++func (repository *gormContactRepository) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Where("id = ?", contactID).+ Delete(&entities.Contact{}).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact with id [%s] for user [%s]", contactID, userID))+ }+ return nil+}++func (repository *gormContactRepository) DeleteAllForUser(ctx context.Context, userID entities.UserID) error {+ ctx, span := repository.tracer.Start(ctx)+ defer span.End()++ if err := repository.db.WithContext(ctx).+ Where("user_id = ?", userID).+ Delete(&entities.Contact{}).Error; err != nil {+ return repository.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete all contacts for user [%s]", userID))+ }+ return nil+}+```++- [ ] **Step 5: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/repositories/ -run TestGormContactRepository`+Expected: PASS++- [ ] **Step 6: Commit**++```bash+git add api/pkg/repositories/contact_repository.go api/pkg/repositories/gorm_contact_repository.go api/pkg/repositories/gorm_contact_repository_test.go+git commit -m "feat(api): add ContactRepository with GORM implementation"+```++---++### Task 4: Contact requests (store / update / index)++**Files:**+- Create: `api/pkg/requests/contact_store.go`+- Create: `api/pkg/requests/contact_update.go`+- Create: `api/pkg/requests/contact_index.go`+- Create: `api/pkg/requests/contact_store_test.go`++**Interfaces:**+- Produces:+ - `requests.ContactItem{ Name string; Emails []string; PhoneNumbers []string; Properties map[string]string }`+ - `requests.ContactStoreRequest{ Contacts []ContactItem }` with `UnmarshalJSON` accepting a JSON array or `{"contacts":[...]}`; methods `Sanitize()` and `ToContacts(userID entities.UserID) []*entities.Contact`.+ - `requests.ContactUpdateRequest{ Name string; Emails []string; PhoneNumbers []string; Properties map[string]string }` with `Sanitize()` and `ApplyTo(contact *entities.Contact)`.+ - `requests.ContactIndex{ Skip, Query, Limit string }` with `Sanitize()` and `ToIndexParams() repositories.IndexParams`.++- [ ] **Step 1: Write the failing test**++Create `api/pkg/requests/contact_store_test.go`:++```go+package requests++import (+ "encoding/json"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestContactStoreRequest_UnmarshalArrayForm(t *testing.T) {+ var request ContactStoreRequest+ require.NoError(t, json.Unmarshal([]byte(`[{"name":"Alice","phone_numbers":["+18005550199"]}]`), &request))+ assert.Equal(t, 1, len(request.Contacts))+ assert.Equal(t, "Alice", request.Contacts[0].Name)+}++func TestContactStoreRequest_UnmarshalObjectForm(t *testing.T) {+ var request ContactStoreRequest+ require.NoError(t, json.Unmarshal([]byte(`{"contacts":[{"name":"Bob","phone_numbers":["+18005550100"]}]}`), &request))+ assert.Equal(t, 1, len(request.Contacts))+ assert.Equal(t, "Bob", request.Contacts[0].Name)+}++func TestContactStoreRequest_SanitizeNormalizesNumbers(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: " Alice ",+ PhoneNumbers: []string{"18005550199"},+ Emails: []string{" [email protected] "},+ }}}+ request = request.Sanitize()+ assert.Equal(t, "Alice", request.Contacts[0].Name)+ assert.Equal(t, "+18005550199", request.Contacts[0].PhoneNumbers[0])+ assert.Equal(t, "[email protected]", request.Contacts[0].Emails[0])+}++func TestContactStoreRequest_ToContacts(t *testing.T) {+ request := ContactStoreRequest{Contacts: []ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ }}}+ contacts := request.ToContacts(entities.UserID("user-1"))+ require.Equal(t, 1, len(contacts))+ assert.Equal(t, "Alice", contacts[0].Name)+ assert.Equal(t, entities.UserID("user-1"), contacts[0].UserID)+ assert.NotEqual(t, "", contacts[0].ID.String())+}+```++- [ ] **Step 2: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/requests/ -run TestContactStoreRequest`+Expected: FAIL / build error — types undefined.++- [ ] **Step 3: Write the implementations**++Create `api/pkg/requests/contact_store.go`:++```go+package requests++import (+ "encoding/json"+ "strings"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/google/uuid"+ "github.com/lib/pq"+)++// ContactItem is a single contact in a create request.+type ContactItem struct {+ Name string `json:"name" example:"Alice Smith"`+ Emails []string `json:"emails"`+ PhoneNumbers []string `json:"phone_numbers"`+ Properties map[string]string `json:"properties"`+}++// ContactStoreRequest creates one or many contacts.+type ContactStoreRequest struct {+ request+ Contacts []ContactItem `json:"contacts"`+}++// UnmarshalJSON accepts either a JSON array of contacts or {"contacts":[...]}.+func (input *ContactStoreRequest) UnmarshalJSON(data []byte) error {+ trimmed := strings.TrimSpace(string(data))+ if strings.HasPrefix(trimmed, "[") {+ var items []ContactItem+ if err := json.Unmarshal(data, &items); err != nil {+ return err+ }+ input.Contacts = items+ return nil+ }++ type alias ContactStoreRequest+ var wrapper alias+ if err := json.Unmarshal(data, &wrapper); err != nil {+ return err+ }+ input.Contacts = wrapper.Contacts+ return nil+}++// Sanitize trims and normalizes each contact item.+func (input ContactStoreRequest) Sanitize() ContactStoreRequest {+ for index := range input.Contacts {+ input.Contacts[index] = input.sanitizeItem(input.Contacts[index])+ }+ return input+}++func (input *ContactStoreRequest) sanitizeItem(item ContactItem) ContactItem {+ item.Name = strings.TrimSpace(item.Name)++ numbers := input.removeStringDuplicates(input.removeEmptyStrings(item.PhoneNumbers))+ item.PhoneNumbers = input.sanitizeAddresses(numbers)++ emails := input.removeEmptyStrings(item.Emails)+ for i := range emails {+ emails[i] = strings.ToLower(strings.TrimSpace(emails[i]))+ }+ item.Emails = input.removeStringDuplicates(emails)++ if item.Properties == nil {+ item.Properties = map[string]string{}+ }+ return item+}++// ToContacts converts the request into persistable entities.Contact records.+func (input *ContactStoreRequest) ToContacts(userID entities.UserID) []*entities.Contact {+ now := time.Now().UTC()+ contacts := make([]*entities.Contact, 0, len(input.Contacts))+ for _, item := range input.Contacts {+ contacts = append(contacts, &entities.Contact{+ ID: uuid.New(),+ UserID: userID,+ Name: item.Name,+ Emails: pq.StringArray(item.Emails),+ PhoneNumbers: pq.StringArray(item.PhoneNumbers),+ Properties: entities.ContactProperties(item.Properties),+ CreatedAt: now,+ UpdatedAt: now,+ })+ }+ return contacts+}+```++Create `api/pkg/requests/contact_update.go`:++```go+package requests++import (+ "strings"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/lib/pq"+)++// ContactUpdateRequest updates an existing contact.+type ContactUpdateRequest struct {+ request+ Name string `json:"name" example:"Alice Smith"`+ Emails []string `json:"emails"`+ PhoneNumbers []string `json:"phone_numbers"`+ Properties map[string]string `json:"properties"`+}++// Sanitize trims and normalizes the update request.+func (input ContactUpdateRequest) Sanitize() ContactUpdateRequest {+ input.Name = strings.TrimSpace(input.Name)++ numbers := input.removeStringDuplicates(input.removeEmptyStrings(input.PhoneNumbers))+ input.PhoneNumbers = input.sanitizeAddresses(numbers)++ emails := input.removeEmptyStrings(input.Emails)+ for i := range emails {+ emails[i] = strings.ToLower(strings.TrimSpace(emails[i]))+ }+ input.Emails = input.removeStringDuplicates(emails)++ if input.Properties == nil {+ input.Properties = map[string]string{}+ }+ return input+}++// ApplyTo mutates an existing contact with the update values.+func (input *ContactUpdateRequest) ApplyTo(contact *entities.Contact) {+ contact.Name = input.Name+ contact.Emails = pq.StringArray(input.Emails)+ contact.PhoneNumbers = pq.StringArray(input.PhoneNumbers)+ contact.Properties = entities.ContactProperties(input.Properties)+ contact.UpdatedAt = time.Now().UTC()+}+```++Create `api/pkg/requests/contact_index.go`:++```go+package requests++import (+ "strings"++ "github.com/NdoleStudio/httpsms/pkg/repositories"+)++// ContactIndex lists contacts for a user.+type ContactIndex struct {+ request+ Skip string `json:"skip" query:"skip"`+ Query string `json:"query" query:"query"`+ Limit string `json:"limit" query:"limit"`+}++// Sanitize sets defaults for the list request.+func (input *ContactIndex) Sanitize() ContactIndex {+ if strings.TrimSpace(input.Limit) == "" {+ input.Limit = "20"+ }+ input.Query = strings.TrimSpace(input.Query)+ input.Skip = strings.TrimSpace(input.Skip)+ if input.Skip == "" {+ input.Skip = "0"+ }+ return *input+}++// ToIndexParams converts the request into repositories.IndexParams.+func (input *ContactIndex) ToIndexParams() repositories.IndexParams {+ return repositories.IndexParams{+ Skip: input.getInt(input.Skip),+ Query: input.Query,+ Limit: input.getInt(input.Limit),+ }+}+```++- [ ] **Step 4: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/requests/ -run TestContactStoreRequest`+Expected: PASS++- [ ] **Step 5: Commit**++```bash+git add api/pkg/requests/contact_store.go api/pkg/requests/contact_update.go api/pkg/requests/contact_index.go api/pkg/requests/contact_store_test.go+git commit -m "feat(api): add contact store/update/index requests"+```++---++### Task 5: ContactHandlerValidator (store / update / index / CSV upload)++**Files:**+- Create: `api/pkg/validators/contact_handler_validator.go`+- Create: `api/pkg/validators/contact_handler_validator_test.go`++**Interfaces:**+- Consumes: `requests.ContactStoreRequest`, `requests.ContactUpdateRequest`, `requests.ContactIndex`, `requests.ContactItem`.+- Produces: `validators.ContactHandlerValidator` with:+ - `NewContactHandlerValidator(logger, tracer) *ContactHandlerValidator`+ - `ValidateStore(ctx, request requests.ContactStoreRequest) url.Values`+ - `ValidateUpdate(ctx, request requests.ContactUpdateRequest) url.Values`+ - `ValidateIndex(ctx, request requests.ContactIndex) url.Values`+ - `ValidateUpload(ctx, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values)`++- [ ] **Step 1: Write the failing test**++Create `api/pkg/validators/contact_handler_validator_test.go`:++```go+package validators++import (+ "context"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/stretchr/testify/assert"+)++func newContactValidator() *ContactHandlerValidator {+ return &ContactHandlerValidator{}+}++func TestContactValidator_ValidateStore_Valid(t *testing.T) {+ v := newContactValidator()+ errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ Emails: []string{"[email protected]"},+ }}})+ assert.Equal(t, 0, len(errs))+}++func TestContactValidator_ValidateStore_MissingName(t *testing.T) {+ v := newContactValidator()+ errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ PhoneNumbers: []string{"+18005550199"},+ }}})+ assert.NotEqual(t, 0, len(errs))+}++func TestContactValidator_ValidateStore_InvalidNumber(t *testing.T) {+ v := newContactValidator()+ errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"not-a-number"},+ }}})+ assert.NotEqual(t, 0, len(errs))+}++func TestContactValidator_ValidateStore_EmptyBatch(t *testing.T) {+ v := newContactValidator()+ errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: nil})+ assert.NotEqual(t, 0, len(errs))+}++func TestContactValidator_ValidateStore_InvalidEmail(t *testing.T) {+ v := newContactValidator()+ errs := v.ValidateStore(context.Background(), requests.ContactStoreRequest{Contacts: []requests.ContactItem{{+ Name: "Alice",+ PhoneNumbers: []string{"+18005550199"},+ Emails: []string{"not-an-email"},+ }}})+ assert.NotEqual(t, 0, len(errs))+}+```++(If `telemetry.NewOtelLogger` for the tracer differs in your package, `ValidateUpload` is the only method needing a real logger/tracer; the store/update/index tests use a zero-value validator.)++- [ ] **Step 2: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/validators/ -run TestContactValidator`+Expected: FAIL / build error — `NewContactHandlerValidator` undefined.++- [ ] **Step 3: Write the implementation**++Create `api/pkg/validators/contact_handler_validator.go`:++```go+package validators++import (+ "bytes"+ "context"+ "fmt"+ "io"+ "mime/multipart"+ "net/mail"+ "net/url"+ "strings"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/jszwec/csvutil"+ "github.com/nyaruka/phonenumbers"+ "github.com/thedevsaddam/govalidator"+)++// ContactHandlerValidator validates models used in handlers.ContactHandler+type ContactHandlerValidator struct {+ validator+ logger telemetry.Logger+ tracer telemetry.Tracer+}++// NewContactHandlerValidator creates a new handlers.ContactHandler validator+func NewContactHandlerValidator(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+) *ContactHandlerValidator {+ return &ContactHandlerValidator{+ logger: logger.WithService(fmt.Sprintf("%T", &ContactHandlerValidator{})),+ tracer: tracer,+ }+}++const maxContactBatch = 1000++// ValidateStore validates a create request of one or many contacts.+func (v *ContactHandlerValidator) ValidateStore(_ context.Context, request requests.ContactStoreRequest) url.Values {+ result := url.Values{}+ if len(request.Contacts) == 0 {+ result.Add("contacts", "You must provide at least one contact.")+ return result+ }+ if len(request.Contacts) > maxContactBatch {+ result.Add("contacts", fmt.Sprintf("You cannot create more than %d contacts in one request.", maxContactBatch))+ return result+ }+ for index, item := range request.Contacts {+ v.validateItem(result, index, item)+ }+ return result+}++// ValidateUpdate validates a single contact update.+func (v *ContactHandlerValidator) ValidateUpdate(_ context.Context, request requests.ContactUpdateRequest) url.Values {+ result := url.Values{}+ v.validateItem(result, 0, requests.ContactItem{+ Name: request.Name,+ Emails: request.Emails,+ PhoneNumbers: request.PhoneNumbers,+ Properties: request.Properties,+ })+ return result+}++func (v *ContactHandlerValidator) validateItem(result url.Values, index int, item requests.ContactItem) {+ row := index + 1+ if strings.TrimSpace(item.Name) == "" {+ result.Add("contacts", fmt.Sprintf("Contact [%d]: The name is required.", row))+ }+ if len(item.PhoneNumbers) == 0 {+ result.Add("contacts", fmt.Sprintf("Contact [%d]: At least one phone number is required.", row))+ }+ for _, number := range item.PhoneNumbers {+ if _, err := phonenumbers.Parse(number, phonenumbers.UNKNOWN_REGION); err != nil {+ result.Add("contacts", fmt.Sprintf("Contact [%d]: The phone number [%s] is not a valid E.164 phone number.", row, number))+ }+ }+ for _, email := range item.Emails {+ if _, err := mail.ParseAddress(email); err != nil {+ result.Add("contacts", fmt.Sprintf("Contact [%d]: The email [%s] is not a valid email address.", row, email))+ }+ }+}++// ValidateIndex validates the list request.+func (v *ContactHandlerValidator) ValidateIndex(_ context.Context, request requests.ContactIndex) url.Values {+ value := govalidator.New(govalidator.Options{+ Data: &request,+ Rules: govalidator.MapData{+ "limit": []string{"required", "numeric", "min:1", "max:100"},+ "skip": []string{"required", "numeric", "min:0"},+ "query": []string{"max:100"},+ },+ })+ return value.ValidateStruct()+}++type contactCSVRow struct {+ Name string `csv:"Name"`+ Emails string `csv:"Emails"`+ PhoneNumbers string `csv:"PhoneNumbers"`+}++// ValidateUpload parses and validates a CSV upload (CSV only).+func (v *ContactHandlerValidator) ValidateUpload(ctx context.Context, userID entities.UserID, header *multipart.FileHeader) ([]requests.ContactItem, url.Values) {+ ctx, span, ctxLogger := v.tracer.StartWithLogger(ctx, v.logger)+ defer span.End()+ _ = ctx++ result := url.Values{}++ if header.Header.Get("Content-Type") != "text/csv" && !strings.HasSuffix(strings.ToLower(header.Filename), ".csv") {+ result.Add("document", fmt.Sprintf("The file [%s] is not a valid CSV file. Only CSV files are supported.", header.Filename))+ return nil, result+ }++ if header.Size >= 500000 {+ result.Add("document", "The CSV file must be less than 500 KB.")+ return nil, result+ }++ file, err := header.Open()+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot open file [%s] for user [%s]", header.Filename, userID))+ result.Add("document", fmt.Sprintf("Cannot open the uploaded file [%s].", header.Filename))+ return nil, result+ }+ defer func() { _ = file.Close() }()++ buffer := new(bytes.Buffer)+ if _, err = io.Copy(buffer, file); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot read file [%s] for user [%s]", header.Filename, userID))+ result.Add("document", fmt.Sprintf("Cannot read the uploaded file [%s].", header.Filename))+ return nil, result+ }++ var rows []contactCSVRow+ if err = csvutil.Unmarshal(buffer.Bytes(), &rows); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot parse CSV file [%s] for user [%s]", header.Filename, userID))+ result.Add("document", fmt.Sprintf("Cannot parse the uploaded CSV file [%s]. Use the official httpSMS contacts template.", header.Filename))+ return nil, result+ }++ if len(rows) > maxContactBatch {+ result.Add("document", fmt.Sprintf("The uploaded file must contain less than %d records.", maxContactBatch))+ return nil, result+ }++ items := make([]requests.ContactItem, 0, len(rows))+ for _, row := range rows {+ if strings.TrimSpace(row.Name) == "" && strings.TrimSpace(row.PhoneNumbers) == "" {+ continue+ }+ items = append(items, requests.ContactItem{+ Name: strings.TrimSpace(row.Name),+ Emails: splitMultiValue(row.Emails),+ PhoneNumbers: splitMultiValue(row.PhoneNumbers),+ })+ }++ if len(items) == 0 {+ result.Add("document", "The uploaded file doesn't contain any valid records.")+ }+ return items, result+}++func splitMultiValue(value string) []string {+ if strings.TrimSpace(value) == "" {+ return nil+ }+ fields := strings.FieldsFunc(value, func(r rune) bool { return r == ';' || r == ',' })+ var result []string+ for _, field := range fields {+ field = strings.TrimSpace(field)+ if field != "" {+ result = append(result, field)+ }+ }+ return result+}+```++- [ ] **Step 4: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/validators/ -run TestContactValidator`+Expected: PASS++- [ ] **Step 5: Commit**++```bash+git add api/pkg/validators/contact_handler_validator.go api/pkg/validators/contact_handler_validator_test.go+git commit -m "feat(api): add ContactHandlerValidator with CSV-only upload parsing"+```++---++### Task 6: ContactService (CRUD + contact-map cache + invalidation)++**Files:**+- Create: `api/pkg/services/contact_service.go`+- Create: `api/pkg/services/contact_service_test.go`++**Interfaces:**+- Consumes: `repositories.ContactRepository`, `cache.Cache`, `entities.Contact`, `repositories.IndexParams`.+- Produces: `services.ContactService` with:+ - `NewContactService(logger, tracer, repository repositories.ContactRepository, appCache cache.Cache) *ContactService`+ - `CreateMany(ctx, userID entities.UserID, contacts []*entities.Contact) error`+ - `Get(ctx, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error)`+ - `Index(ctx, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error)`+ - `Update(ctx, contact *entities.Contact) error`+ - `Delete(ctx, userID entities.UserID, contactID uuid.UUID) error`+ - `GetContactMap(ctx, userID entities.UserID) (map[string]*entities.Contact, error)` (cache-backed; most-recently-updated wins)++- [ ] **Step 1: Write the failing test**++Create `api/pkg/services/contact_service_test.go`:++```go+package services++import (+ "context"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+ "github.com/lib/pq"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type fakeCache struct {+ store map[string]string+}++func newFakeCache() *fakeCache { return &fakeCache{store: map[string]string{}} }++func (c *fakeCache) Get(_ context.Context, key string) (string, error) {+ value, ok := c.store[key]+ if !ok {+ return "", assertMiss{}+ }+ return value, nil+}++func (c *fakeCache) Set(_ context.Context, key, value string, _ time.Duration) error {+ c.store[key] = value+ return nil+}++type assertMiss struct{}++func (assertMiss) Error() string { return "miss" }++type fakeContactRepo struct {+ contacts []*entities.Contact+ fetchAll int+}++func (r *fakeContactRepo) Store(_ context.Context, contacts []*entities.Contact) error {+ r.contacts = append(r.contacts, contacts...)+ return nil+}+func (r *fakeContactRepo) Update(_ context.Context, contact *entities.Contact) error { return nil }+func (r *fakeContactRepo) Load(_ context.Context, _ entities.UserID, id uuid.UUID) (*entities.Contact, error) {+ for _, c := range r.contacts {+ if c.ID == id {+ return c, nil+ }+ }+ return nil, stacktrace.NewErrorWithCodef(repositories.ErrCodeNotFound, "contact [%s] not found", id)+}+func (r *fakeContactRepo) Index(_ context.Context, _ entities.UserID, _ repositories.IndexParams) (*[]entities.Contact, error) {+ out := []entities.Contact{}+ return &out, nil+}+func (r *fakeContactRepo) FetchAll(_ context.Context, _ entities.UserID) (*[]entities.Contact, error) {+ r.fetchAll+++ out := make([]entities.Contact, 0, len(r.contacts))+ for _, c := range r.contacts {+ out = append(out, *c)+ }+ return &out, nil+}+func (r *fakeContactRepo) Delete(_ context.Context, _ entities.UserID, _ uuid.UUID) error { return nil }+func (r *fakeContactRepo) DeleteAllForUser(_ context.Context, _ entities.UserID) error { return nil }++func newContactService(repo repositories.ContactRepository, appCache *fakeCache) *ContactService {+ logger := telemetry.NewZerologLogger("test", nil, nil, nil)+ return NewContactService(logger, telemetry.NewOtelLogger("test", logger), repo, appCache)+}++func TestContactService_GetContactMap_TieBreakMostRecentlyUpdated(t *testing.T) {+ older := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "Old", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now().Add(-time.Hour)}+ newer := &entities.Contact{ID: uuid.New(), UserID: "u1", Name: "New", PhoneNumbers: pq.StringArray{"+18005550199"}, UpdatedAt: time.Now()}+ // FetchAll returns ASC by updated_at, so older first then newer.+ repo := &fakeContactRepo{contacts: []*entities.Contact{older, newer}}+ service := newContactService(repo, newFakeCache())++ result, err := service.GetContactMap(context.Background(), entities.UserID("u1"))+ require.NoError(t, err)+ require.NotNil(t, result["+18005550199"])+ assert.Equal(t, "New", result["+18005550199"].Name)+}++func TestContactService_GetContactMap_UsesCacheOnSecondCall(t *testing.T) {+ repo := &fakeContactRepo{contacts: []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}}+ service := newContactService(repo, newFakeCache())++ _, err := service.GetContactMap(context.Background(), entities.UserID("u1"))+ require.NoError(t, err)+ _, err = service.GetContactMap(context.Background(), entities.UserID("u1"))+ require.NoError(t, err)++ assert.Equal(t, 1, repo.fetchAll)+}++func TestContactService_CreateMany_InvalidatesCache(t *testing.T) {+ repo := &fakeContactRepo{contacts: []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Alice", PhoneNumbers: pq.StringArray{"+18005550199"}}}}+ appCache := newFakeCache()+ service := newContactService(repo, appCache)++ _, err := service.GetContactMap(context.Background(), entities.UserID("u1"))+ require.NoError(t, err)+ require.Equal(t, 1, repo.fetchAll)++ require.NoError(t, service.CreateMany(context.Background(), entities.UserID("u1"), []*entities.Contact{{ID: uuid.New(), UserID: "u1", Name: "Bob", PhoneNumbers: pq.StringArray{"+18005550100"}}}))++ _, err = service.GetContactMap(context.Background(), entities.UserID("u1"))+ require.NoError(t, err)+ assert.Equal(t, 2, repo.fetchAll)+}+```++- [ ] **Step 2: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/services/ -run TestContactService`+Expected: FAIL / build error — `NewContactService` undefined.++- [ ] **Step 3: Write the implementation**++Create `api/pkg/services/contact_service.go`:++```go+package services++import (+ "context"+ "encoding/json"+ "fmt"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/cache"+ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/stacktrace"+ "github.com/google/uuid"+)++const contactMapCacheTTL = 24 * time.Hour++// ContactService handles contact business logic.+type ContactService struct {+ service+ logger telemetry.Logger+ tracer telemetry.Tracer+ repository repositories.ContactRepository+ cache cache.Cache+}++// NewContactService creates a new ContactService.+func NewContactService(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ repository repositories.ContactRepository,+ appCache cache.Cache,+) (s *ContactService) {+ return &ContactService{+ logger: logger.WithService(fmt.Sprintf("%T", s)),+ tracer: tracer,+ repository: repository,+ cache: appCache,+ }+}++func (service *ContactService) cacheKey(userID entities.UserID) string {+ return fmt.Sprintf("contacts.map.%s", userID)+}++// CreateMany persists one or many contacts then invalidates the cache.+func (service *ContactService) CreateMany(ctx context.Context, userID entities.UserID, contacts []*entities.Contact) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.Store(ctx, contacts); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot store [%d] contacts for user [%s]", len(contacts), userID))+ }+ service.invalidate(ctx, userID)+ return nil+}++// Get returns a contact by ID.+func (service *ContactService) Get(ctx context.Context, userID entities.UserID, contactID uuid.UUID) (*entities.Contact, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ contact, err := service.repository.Load(ctx, userID, contactID)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.PropagateWithCodef(err, stacktrace.GetCode(err), "cannot load contact [%s] for user [%s]", contactID, userID))+ }+ return contact, nil+}++// Index lists contacts for a user.+func (service *ContactService) Index(ctx context.Context, userID entities.UserID, params repositories.IndexParams) (*[]entities.Contact, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ contacts, err := service.repository.Index(ctx, userID, params)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot index contacts for user [%s]", userID))+ }+ return contacts, nil+}++// Update saves a contact and invalidates the cache.+func (service *ContactService) Update(ctx context.Context, contact *entities.Contact) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.Update(ctx, contact); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot update contact [%s]", contact.ID))+ }+ service.invalidate(ctx, contact.UserID)+ return nil+}++// Delete removes a contact and invalidates the cache.+func (service *ContactService) Delete(ctx context.Context, userID entities.UserID, contactID uuid.UUID) error {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if err := service.repository.Delete(ctx, userID, contactID); err != nil {+ return service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))+ }+ service.invalidate(ctx, userID)+ return nil+}++// GetContactMap returns the cached phone_number -> *Contact map for a user.+func (service *ContactService) GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ if raw, err := service.cache.Get(ctx, service.cacheKey(userID)); err == nil && raw != "" {+ result := map[string]*entities.Contact{}+ if jsonErr := json.Unmarshal([]byte(raw), &result); jsonErr == nil {+ return result, nil+ }+ }++ contacts, err := service.repository.FetchAll(ctx, userID)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "cannot fetch contacts to build map for user [%s]", userID))+ }++ // FetchAll returns updated_at ASC, so later (more recently updated) contacts overwrite earlier ones.+ result := map[string]*entities.Contact{}+ for index := range *contacts {+ contact := (*contacts)[index]+ for _, number := range contact.PhoneNumbers {+ copied := contact+ result[number] = &copied+ }+ }++ if encoded, encodeErr := json.Marshal(result); encodeErr == nil {+ _ = service.cache.Set(ctx, service.cacheKey(userID), string(encoded), contactMapCacheTTL)+ }++ return result, nil+}++// invalidate overwrites the cache key with an empty marker (Cache has no Delete).+func (service *ContactService) invalidate(ctx context.Context, userID entities.UserID) {+ if err := service.cache.Set(ctx, service.cacheKey(userID), "", contactMapCacheTTL); err != nil {+ service.logger.Error(stacktrace.Propagatef(err, "cannot invalidate contact map cache for user [%s]", userID))+ }+}+```++- [ ] **Step 4: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/services/ -run TestContactService`+Expected: PASS++- [ ] **Step 5: Commit**++```bash+git add api/pkg/services/contact_service.go api/pkg/services/contact_service_test.go+git commit -m "feat(api): add ContactService with cached contact-map resolution"+```++---++### Task 7: Opt-in contact resolution in GetThreads++**Files:**+- Modify: `api/pkg/services/message_thread_service.go` (struct, constructor, `MessageThreadGetParams`, `GetThreads`)+- Modify: `api/pkg/requests/message_thread_index_request.go` (`Contacts` param + `ToGetParams`)+- Modify: `api/pkg/handlers/message_thread_handler_test.go` (add 6th constructor arg)+- Create: `api/pkg/services/message_thread_service_contacts_test.go`+- Create: `api/pkg/requests/message_thread_index_request_test.go`++**Interfaces:**+- Consumes: `ContactService.GetContactMap(ctx, userID) (map[string]*entities.Contact, error)` (Task 6); `entities.MessageThread.ContactDetails` (Task 2).+- Produces: `MessageThreadGetParams.WithContacts bool`; `MessageThreadService` gains a `contactService contactMapProvider` field where `contactMapProvider` is:+ ```go+ type contactMapProvider interface {+ GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error)+ }+ ```+ `*ContactService` satisfies `contactMapProvider`. New constructor signature:+ `NewMessageThreadService(logger, tracer, repository, phoneRepository, eventDispatcher, contactService contactMapProvider) *MessageThreadService`++- [ ] **Step 1: Write the failing tests**++Create `api/pkg/requests/message_thread_index_request_test.go`:++```go+package requests++import (+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/stretchr/testify/assert"+)++func TestMessageThreadIndex_ToGetParams_WithContacts(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199", Contacts: "true"}).Sanitize()+ params := input.ToGetParams(entities.UserID("u1"))+ assert.True(t, params.WithContacts)+}++func TestMessageThreadIndex_ToGetParams_WithoutContacts(t *testing.T) {+ input := (&MessageThreadIndex{Owner: "+18005550199"}).Sanitize()+ params := input.ToGetParams(entities.UserID("u1"))+ assert.False(t, params.WithContacts)+}+```++Create `api/pkg/services/message_thread_service_contacts_test.go`:++```go+package services++import (+ "context"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type stubThreadRepo struct {+ repositories.MessageThreadRepository+ threads []entities.MessageThread+}++func (r *stubThreadRepo) Index(_ context.Context, _ entities.UserID, _ string, _ bool, _ repositories.IndexParams) (*[]entities.MessageThread, error) {+ out := make([]entities.MessageThread, len(r.threads))+ copy(out, r.threads)+ return &out, nil+}++type stubContactProvider struct {+ contactMap map[string]*entities.Contact+ calls int+}++func (p *stubContactProvider) GetContactMap(_ context.Context, _ entities.UserID) (map[string]*entities.Contact, error) {+ p.calls+++ return p.contactMap, nil+}++func newThreadServiceWithContacts(repo repositories.MessageThreadRepository, provider contactMapProvider) *MessageThreadService {+ logger := telemetry.NewZerologLogger("test", nil, nil, nil)+ return NewMessageThreadService(logger, telemetry.NewOtelLogger("test", logger), repo, nil, nil, provider)+}++func TestGetThreads_AttachesContactDetailsWhenWithContacts(t *testing.T) {+ repo := &stubThreadRepo{threads: []entities.MessageThread{{Contact: "+18005550199"}, {Contact: "+18005550100"}}}+ provider := &stubContactProvider{contactMap: map[string]*entities.Contact{"+18005550199": {Name: "Alice"}}}+ service := newThreadServiceWithContacts(repo, provider)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: "u1", WithContacts: true})+ require.NoError(t, err)+ require.Len(t, *threads, 2)+ require.NotNil(t, (*threads)[0].ContactDetails)+ assert.Equal(t, "Alice", (*threads)[0].ContactDetails.Name)+ assert.Nil(t, (*threads)[1].ContactDetails)+}++func TestGetThreads_SkipsContactLookupWhenFlagOff(t *testing.T) {+ repo := &stubThreadRepo{threads: []entities.MessageThread{{Contact: "+18005550199"}}}+ provider := &stubContactProvider{contactMap: map[string]*entities.Contact{"+18005550199": {Name: "Alice"}}}+ service := newThreadServiceWithContacts(repo, provider)++ threads, err := service.GetThreads(context.Background(), MessageThreadGetParams{UserID: "u1", WithContacts: false})+ require.NoError(t, err)+ assert.Nil(t, (*threads)[0].ContactDetails)+ assert.Equal(t, 0, provider.calls)+}+```++- [ ] **Step 2: Run tests to verify they fail**++Run: `cd api && go test -vet=off ./pkg/requests/ -run TestMessageThreadIndex_ToGetParams && go test -vet=off ./pkg/services/ -run TestGetThreads`+Expected: FAIL / build error — `Contacts`, `WithContacts`, and the 6-arg constructor do not exist yet.++- [ ] **Step 3: Implement request changes**++In `api/pkg/requests/message_thread_index_request.go`, add the field to the struct:++```go+ Owner string `json:"owner" query:"owner"`+ Contacts string `json:"contacts" query:"contacts" example:"true"`+```++Add sanitisation inside `Sanitize()` (before `return *input`):++```go+ input.Contacts = input.sanitizeBool(input.Contacts)+```++Add the field to the returned params in `ToGetParams`:++```go+ UserID: userID,+ IsArchived: input.getBool(input.IsArchived),+ Owner: input.Owner,+ WithContacts: input.getBool(input.Contacts),+ }+```++- [ ] **Step 4: Implement service changes**++In `api/pkg/services/message_thread_service.go` add the provider interface (top-level, after imports):++```go+// contactMapProvider supplies the phone_number -> *Contact map for a user.+type contactMapProvider interface {+ GetContactMap(ctx context.Context, userID entities.UserID) (map[string]*entities.Contact, error)+}+```++Add the field to the struct:++```go+ eventDispatcher *EventDispatcher+ contactService contactMapProvider+```++Update the constructor:++```go+func NewMessageThreadService(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ repository repositories.MessageThreadRepository,+ phoneRepository repositories.PhoneRepository,+ eventDispatcher *EventDispatcher,+ contactService contactMapProvider,+) (s *MessageThreadService) {+ return &MessageThreadService{+ logger: logger.WithService(fmt.Sprintf("%T", s)),+ tracer: tracer,+ eventDispatcher: eventDispatcher,+ repository: repository,+ phoneRepository: phoneRepository,+ contactService: contactService,+ }+}+```++Add `WithContacts` to the params struct:++```go+type MessageThreadGetParams struct {+ repositories.IndexParams+ IsArchived bool+ WithContacts bool+ UserID entities.UserID+ Owner string+}+```++Extend `GetThreads` to attach contact details (replace its body):++```go+func (service *MessageThreadService) GetThreads(ctx context.Context, params MessageThreadGetParams) (*[]entities.MessageThread, error) {+ ctx, span := service.tracer.Start(ctx)+ defer span.End()++ ctxLogger := service.tracer.CtxLogger(service.logger, span)++ threads, err := service.repository.Index(ctx, params.UserID, params.Owner, params.IsArchived, params.IndexParams)+ if err != nil {+ return nil, service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(err, "could not fetch messages threads for params [%+#v]", params))+ }++ if params.WithContacts && service.contactService != nil && len(*threads) > 0 {+ contactMap, mapErr := service.contactService.GetContactMap(ctx, params.UserID)+ if mapErr != nil {+ ctxLogger.Error(service.tracer.WrapErrorSpan(span, stacktrace.Propagatef(mapErr, "cannot build contact map for user [%s]", params.UserID)))+ } else {+ for index := range *threads {+ if contact, ok := contactMap[(*threads)[index].Contact]; ok {+ (*threads)[index].ContactDetails = contact+ }+ }+ }+ }++ ctxLogger.Info(fmt.Sprintf("fetched [%d] threads with params [%+#v]", len(*threads), params))+ return threads, nil+}+```++- [ ] **Step 5: Update DI wiring and existing callers**++In `api/pkg/di/container.go`, find `NewMessageThreadService(...)` and append `container.ContactService()` as the final argument (the `ContactService()` getter is added in Task 8; if wiring Task 8 first, this compiles immediately — otherwise temporarily pass `nil` and restore in Task 8).++Also update the existing test `api/pkg/handlers/message_thread_handler_test.go`: its call `services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil)` now needs a sixth argument — change it to `services.NewMessageThreadService(logger, tracer, &messageThreadHandlerRepositoryStub{}, nil, nil, nil)`.++- [ ] **Step 6: Run tests to verify they pass**++Run: `cd api && go test -vet=off ./pkg/requests/ -run TestMessageThreadIndex_ToGetParams && go test -vet=off ./pkg/services/ -run TestGetThreads`+Expected: PASS++- [ ] **Step 7: Commit**++```bash+git add api/pkg/services/message_thread_service.go api/pkg/services/message_thread_service_contacts_test.go api/pkg/requests/message_thread_index_request.go api/pkg/requests/message_thread_index_request_test.go api/pkg/handlers/message_thread_handler_test.go api/pkg/di/container.go+git commit -m "feat(api): opt-in contact resolution for message threads via ?contacts=true"+```++---++### Task 8: ContactHandler + DI wiring + route registration++**Files:**+- Create: `api/pkg/handlers/contact_handler.go`+- Create: `api/pkg/handlers/contact_handler_test.go`+- Modify: `api/pkg/di/container.go` (getters, AutoMigrate, RegisterContactRoutes, wire ContactService into MessageThreadService)++**Interfaces:**+- Consumes: `services.ContactService` (Task 6), `validators.ContactHandlerValidator` (Task 5), `requests.*` (Task 4), `repositories.ErrCodeNotFound`.+- Produces: `handlers.ContactHandler` with `NewContactHandler(logger, tracer, validator *validators.ContactHandlerValidator, service *services.ContactService) *ContactHandler` and `RegisterRoutes(router, ...middlewares)`. Routes: `GET /v1/contacts`, `POST /v1/contacts`, `POST /v1/contacts/upload`, `PUT /v1/contacts/:contactID`, `DELETE /v1/contacts/:contactID`. New DI getters: `container.ContactRepository()`, `container.ContactService()`, `container.ContactHandlerValidator()`, `container.ContactHandler()`, `container.RegisterContactRoutes()`.++- [ ] **Step 1: Write the failing test**++Create `api/pkg/handlers/contact_handler_test.go`:++```go+package handlers++import (+ "bytes"+ "context"+ "net/http"+ "net/http/httptest"+ "testing"+ "time"++ "github.com/NdoleStudio/httpsms/pkg/cache"+ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/middlewares"+ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/httpsms/pkg/validators"+ "github.com/gofiber/fiber/v3"+ "github.com/google/uuid"+ ttlCache "github.com/patrickmn/go-cache"+ "github.com/stretchr/testify/require"+)++type contactHandlerRepoStub struct {+ stored []*entities.Contact+}++func (s *contactHandlerRepoStub) Store(_ context.Context, contacts []*entities.Contact) error {+ s.stored = append(s.stored, contacts...)+ return nil+}+func (s *contactHandlerRepoStub) Update(context.Context, *entities.Contact) error { return nil }+func (s *contactHandlerRepoStub) Load(context.Context, entities.UserID, uuid.UUID) (*entities.Contact, error) {+ return nil, nil+}+func (s *contactHandlerRepoStub) Index(context.Context, entities.UserID, repositories.IndexParams) (*[]entities.Contact, error) {+ out := []entities.Contact{}+ return &out, nil+}+func (s *contactHandlerRepoStub) FetchAll(context.Context, entities.UserID) (*[]entities.Contact, error) {+ out := []entities.Contact{}+ return &out, nil+}+func (s *contactHandlerRepoStub) Delete(context.Context, entities.UserID, uuid.UUID) error { return nil }+func (s *contactHandlerRepoStub) DeleteAllForUser(context.Context, entities.UserID) error { return nil }++func newContactTestApp(repo repositories.ContactRepository) *fiber.App {+ logger := &messageThreadHandlerNoopLogger{}+ tracer := telemetry.NewOtelLogger("test", logger)+ appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))+ service := services.NewContactService(logger, tracer, repo, appCache)+ handler := NewContactHandler(logger, tracer, &validators.ContactHandlerValidator{}, service)++ app := fiber.New()+ app.Use(func(c fiber.Ctx) error {+ c.Locals(middlewares.ContextKeyAuthUserID, entities.AuthContext{ID: entities.UserID("user-id"), Email: "[email protected]"})+ return c.Next()+ })+ handler.RegisterRoutes(app)+ return app+}++func TestContactHandler_Store_CreatesContacts(t *testing.T) {+ repo := &contactHandlerRepoStub{}+ app := newContactTestApp(repo)++ body := `[{"name":"Alice","phone_numbers":["+18005550199"]}]`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, resp.StatusCode)+ require.Len(t, repo.stored, 1)+ require.Equal(t, "Alice", repo.stored[0].Name)+}++func TestContactHandler_Store_ValidationError(t *testing.T) {+ app := newContactTestApp(&contactHandlerRepoStub{})++ body := `[{"name":"","phone_numbers":[]}]`+ req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")++ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusUnprocessableEntity, resp.StatusCode)+}++func TestContactHandler_Index_ReturnsOK(t *testing.T) {+ app := newContactTestApp(&contactHandlerRepoStub{})++ req := httptest.NewRequest(http.MethodGet, "/v1/contacts", nil)+ resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode)+}+```++- [ ] **Step 2: Run test to verify it fails**++Run: `cd api && go test -vet=off ./pkg/handlers/ -run TestContactHandler`+Expected: FAIL / build error — `NewContactHandler` undefined.++- [ ] **Step 3: Write the handler**++Create `api/pkg/handlers/contact_handler.go`:++```go+package handlers++import (+ "fmt"++ "github.com/NdoleStudio/httpsms/pkg/repositories"+ "github.com/NdoleStudio/httpsms/pkg/requests"+ "github.com/NdoleStudio/httpsms/pkg/services"+ "github.com/NdoleStudio/httpsms/pkg/telemetry"+ "github.com/NdoleStudio/httpsms/pkg/validators"+ "github.com/NdoleStudio/stacktrace"+ "github.com/davecgh/go-spew/spew"+ "github.com/gofiber/fiber/v3"+ "github.com/google/uuid"+)++// ContactHandler handles contact http requests.+type ContactHandler struct {+ handler+ logger telemetry.Logger+ tracer telemetry.Tracer+ validator *validators.ContactHandlerValidator+ service *services.ContactService+}++// NewContactHandler creates a new ContactHandler.+func NewContactHandler(+ logger telemetry.Logger,+ tracer telemetry.Tracer,+ validator *validators.ContactHandlerValidator,+ service *services.ContactService,+) (h *ContactHandler) {+ return &ContactHandler{+ logger: logger.WithService(fmt.Sprintf("%T", h)),+ tracer: tracer,+ validator: validator,+ service: service,+ }+}++// RegisterRoutes registers the routes for the ContactHandler.+func (h *ContactHandler) RegisterRoutes(router fiber.Router, middlewares ...fiber.Handler) {+ h.register(router, fiber.MethodGet, "/v1/contacts", middlewares, h.Index)+ h.register(router, fiber.MethodPost, "/v1/contacts", middlewares, h.Store)+ h.register(router, fiber.MethodPost, "/v1/contacts/upload", middlewares, h.Upload)+ h.register(router, fiber.MethodPut, "/v1/contacts/:contactID", middlewares, h.Update)+ h.register(router, fiber.MethodDelete, "/v1/contacts/:contactID", middlewares, h.Delete)+}++// Index lists contacts for the authenticated user.+// @Summary List contacts+// @Description Returns the paginated list of contacts for the authenticated user.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param skip query int false "number of contacts to skip" minimum(0)+// @Param query query string false "filter contacts containing query"+// @Param limit query int false "number of contacts to return" minimum(1) maximum(100)+// @Success 200 {object} responses.ContactsResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts [get]+func (h *ContactHandler) Index(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ var request requests.ContactIndex+ if err := c.Bind().Query(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall params [%s] into %T", c.OriginalURL(), request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateIndex(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while listing contacts [%+#v]", spew.Sdump(errors), sanitized))+ return h.responseUnprocessableEntity(c, errors, "validation errors while listing contacts")+ }++ contacts, err := h.service.Index(ctx, h.userIDFomContext(c), sanitized.ToIndexParams())+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot list contacts for user [%s]", h.userIDFomContext(c)))+ return h.responseInternalServerError(c)+ }++ return h.responseOK(c, fmt.Sprintf("fetched %d %s", len(*contacts), h.pluralize("contact", len(*contacts))), contacts)+}++// Store creates one or many contacts.+// @Summary Create one or many contacts+// @Description Creates a single contact or a batch of contacts. Accepts a JSON array or an object with a "contacts" array.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param payload body requests.ContactStoreRequest true "Contact(s) to create"+// @Success 201 {object} responses.ContactsResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts [post]+func (h *ContactHandler) Store(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ var request requests.ContactStoreRequest+ if err := c.Bind().Body(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body [%s] into %T", c.Body(), request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateStore(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while creating contacts", spew.Sdump(errors)))+ return h.responseUnprocessableEntity(c, errors, "validation errors while creating contacts")+ }++ userID := h.userIDFomContext(c)+ contacts := sanitized.ToContacts(userID)+ if err := h.service.CreateMany(ctx, userID, contacts); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot create [%d] contacts for user [%s]", len(contacts), userID))+ return h.responseInternalServerError(c)+ }++ return h.responseCreated(c, fmt.Sprintf("created %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)+}++// Upload imports contacts from a CSV file.+// @Summary Import contacts from CSV+// @Description Uploads a CSV file (multipart field "document") of contacts. Columns: Name, Emails, PhoneNumbers (multi-values separated by ";").+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept multipart/form-data+// @Produce json+// @Param document formData file true "CSV file of contacts"+// @Success 201 {object} responses.ContactsResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/upload [post]+func (h *ContactHandler) Upload(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ file, err := c.FormFile("document")+ if err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot fetch file with name [%s] from request", "document"))+ return h.responseBadRequest(c, err)+ }++ userID := h.userIDFomContext(c)+ items, errors := h.validator.ValidateUpload(ctx, userID, file)+ if len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while importing contacts from CSV [%s]", spew.Sdump(errors), file.Filename))+ return h.responseUnprocessableEntity(c, errors, "validation errors while importing contacts")+ }++ request := (requests.ContactStoreRequest{Contacts: items}).Sanitize()+ contacts := request.ToContacts(userID)+ if err = h.service.CreateMany(ctx, userID, contacts); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot import [%d] contacts for user [%s]", len(contacts), userID))+ return h.responseInternalServerError(c)+ }++ return h.responseCreated(c, fmt.Sprintf("imported %d %s", len(contacts), h.pluralize("contact", len(contacts))), contacts)+}++// Update updates a single contact.+// @Summary Update a contact+// @Description Updates the details of a single contact.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param contactID path string true "ID of the contact"+// @Param payload body requests.ContactUpdateRequest true "Contact details to update"+// @Success 200 {object} responses.ContactResponse+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 404 {object} responses.NotFound+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/{contactID} [put]+func (h *ContactHandler) Update(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ contactID := c.Params("contactID")+ if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")+ }++ var request requests.ContactUpdateRequest+ if err := c.Bind().Body(&request); err != nil {+ ctxLogger.Warn(stacktrace.Propagatef(err, "cannot marshall body into %T", request))+ return h.responseBadRequest(c, err)+ }++ sanitized := request.Sanitize()+ if errors := h.validator.ValidateUpdate(ctx, sanitized); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while updating contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while updating contact")+ }++ userID := h.userIDFomContext(c)+ contact, err := h.service.Get(ctx, userID, uuid.MustParse(contactID))+ if stacktrace.GetCode(err) == repositories.ErrCodeNotFound {+ return h.responseNotFound(c, fmt.Sprintf("cannot find contact with ID [%s]", contactID))+ }+ if err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot load contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ sanitized.ApplyTo(contact)+ if err = h.service.Update(ctx, contact); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot update contact [%s]", contactID))+ return h.responseInternalServerError(c)+ }++ return h.responseOK(c, "contact updated successfully", contact)+}++// Delete removes a single contact.+// @Summary Delete a contact+// @Description Deletes a single contact from the database.+// @Security ApiKeyAuth+// @Tags Contacts+// @Accept json+// @Produce json+// @Param contactID path string true "ID of the contact"+// @Success 204 {object} responses.NoContent+// @Failure 400 {object} responses.BadRequest+// @Failure 401 {object} responses.Unauthorized+// @Failure 404 {object} responses.NotFound+// @Failure 422 {object} responses.UnprocessableEntity+// @Failure 500 {object} responses.InternalServerError+// @Router /contacts/{contactID} [delete]+func (h *ContactHandler) Delete(c fiber.Ctx) error {+ ctx, span, ctxLogger := h.tracer.StartFromFiberCtxWithLogger(c, h.logger)+ defer span.End()++ contactID := c.Params("contactID")+ if errors := h.validator.ValidateUUID(contactID, "contactID"); len(errors) != 0 {+ ctxLogger.Warn(stacktrace.NewErrorf("validation errors [%s], while deleting contact [%s]", spew.Sdump(errors), contactID))+ return h.responseUnprocessableEntity(c, errors, "validation errors while deleting contact")+ }++ userID := h.userIDFomContext(c)+ if err := h.service.Delete(ctx, userID, uuid.MustParse(contactID)); err != nil {+ ctxLogger.Error(stacktrace.Propagatef(err, "cannot delete contact [%s] for user [%s]", contactID, userID))+ return h.responseInternalServerError(c)+ }++ return h.responseNoContent(c, "contact deleted successfully")+}+```++- [ ] **Step 4: Add DI getters and wiring**++In `api/pkg/di/container.go`:++Add a repository getter (near `MessageThreadRepository`):++```go+// ContactRepository creates a new instance of repositories.ContactRepository+func (container *Container) ContactRepository() (repository repositories.ContactRepository) {+ container.logger.Debug("creating GORM repositories.ContactRepository")+ return repositories.NewGormContactRepository(+ container.Logger(),+ container.Tracer(),+ container.DB(),+ )+}+```++Add a service getter (near `MessageThreadService`):++```go+// ContactService creates a new instance of services.ContactService+func (container *Container) ContactService() (service *services.ContactService) {+ container.logger.Debug(fmt.Sprintf("creating %T", service))+ return services.NewContactService(+ container.Logger(),+ container.Tracer(),+ container.ContactRepository(),+ container.Cache(),+ )+}+```++Add a validator getter (near `MessageThreadHandlerValidator`):++```go+// ContactHandlerValidator creates a new instance of validators.ContactHandlerValidator+func (container *Container) ContactHandlerValidator() (validator *validators.ContactHandlerValidator) {+ container.logger.Debug(fmt.Sprintf("creating %T", validator))+ return validators.NewContactHandlerValidator(+ container.Logger(),+ container.Tracer(),+ )+}+```++Add a handler getter (near `MessageThreadHandler`):++```go+// ContactHandler creates a new instance of handlers.ContactHandler+func (container *Container) ContactHandler() (h *handlers.ContactHandler) {+ container.logger.Debug(fmt.Sprintf("creating %T", h))+ return handlers.NewContactHandler(+ container.Logger(),+ container.Tracer(),+ container.ContactHandlerValidator(),+ container.ContactService(),+ )+}+```++Add a route registrar (near `RegisterMessageThreadRoutes`):++```go+// RegisterContactRoutes registers routes for the /contacts prefix+func (container *Container) RegisterContactRoutes() {+ container.logger.Debug(fmt.Sprintf("registering %T routes", &handlers.ContactHandler{}))+ container.ContactHandler().RegisterRoutes(container.App(), container.AuthenticatedMiddleware())+}+```++Call the registrar right after `container.RegisterMessageThreadRoutes()` (around line 123):++```go+ container.RegisterMessageThreadRoutes()+ container.RegisterContactRoutes()+```++Wire the ContactService into MessageThreadService (finalise Task 7 Step 5): the `MessageThreadService()` getter's `NewMessageThreadService(...)` call's final argument becomes `container.ContactService()`:++```go+ return services.NewMessageThreadService(+ container.Logger(),+ container.Tracer(),+ container.MessageThreadRepository(),+ container.PhoneRepository(),+ container.EventDispatcher(),+ container.ContactService(),+ )+```++Add the AutoMigrate entry in the AutoMigrate block (around line 413, alongside the other `db.AutoMigrate(&entities.X{})` calls) — this may already be present from Task 2; if not, add:++```go+ if err = db.AutoMigrate(&entities.Contact{}); err != nil {+ container.logger.Fatal(stacktrace.Propagatef(err, "cannot migrate %T", &entities.Contact{}))+ }+```++- [ ] **Step 5: Run test to verify it passes**++Run: `cd api && go test -vet=off ./pkg/handlers/ -run TestContactHandler`+Expected: PASS++- [ ] **Step 6: Build the whole API to confirm wiring compiles**++Run: `cd api && go build ./...`+Expected: no output (success).++- [ ] **Step 7: Commit**++```bash+git add api/pkg/handlers/contact_handler.go api/pkg/handlers/contact_handler_test.go api/pkg/di/container.go+git commit -m "feat(api): add ContactHandler and wire contacts into DI container"+```++---++### Task 9: Swagger regeneration + CSV import template++**Files:**+- Modify: `api/docs/*` (generated by swag)+- Create: `web/public/templates/httpsms-contacts.csv`+- Create/verify: `api/pkg/responses/` contact response types if referenced by Swagger annotations (see Step 1).++**Interfaces:**+- Consumes: Swagger annotations added on `ContactHandler` (Task 8), which reference `responses.ContactResponse` and `responses.ContactsResponse`.+- Produces: regenerated `api/docs/swagger.json` / `swagger.yaml` / `docs.go` including the `/contacts` endpoints; a downloadable CSV template served by the web app.++- [ ] **Step 1: Add response wrapper types (if missing)**++Check whether `responses.ContactResponse` and `responses.ContactsResponse` exist:++Run: `cd api && findstr /S /C:"ContactsResponse" pkg\responses\*.go`+Expected: no matches (they don't exist yet).++Create `api/pkg/responses/contact_responses.go`:++```go+package responses++import "github.com/NdoleStudio/httpsms/pkg/entities"++// ContactResponse is the response with a single entities.Contact.+type ContactResponse struct {+ response+ Data entities.Contact `json:"data"`+}++// ContactsResponse is the response with a list of entities.Contact.+type ContactsResponse struct {+ response+ Data []entities.Contact `json:"data"`+}+```++(Verify the base embedded type name: open any file in `api/pkg/responses/` and confirm the unexported base struct is `response` with `Status`/`Message` fields; match the exact embed used by e.g. `MessageThreadsResponse`.)++- [ ] **Step 2: Regenerate Swagger docs**++Run:++```bash+cd api && swag init --requiredByDefault --parseDependency --parseInternal+```++Expected: `create docs/docs.go`, `create docs/swagger.json`, `create docs/swagger.yaml` with no errors. Confirm `/contacts` appears:++Run: `cd api && findstr /C:"/contacts" docs\swagger.json`+Expected: matches for `/contacts`, `/contacts/upload`, `/contacts/{contactID}`.++- [ ] **Step 3: Create the CSV import template**++Create `web/public/templates/httpsms-contacts.csv`:++```csv+Name,Emails,PhoneNumbers+John Doe,[email protected],+18005550199+Jane Smith,[email protected];[email protected],+18005550100;+18005550111+Acme Support,,+18005550122+```++(Multiple emails or phone numbers in one cell are separated by `;`, matching the CSV parser in Task 5's `ValidateUpload`.)++- [ ] **Step 4: Commit**++```bash+git add api/docs api/pkg/responses/contact_responses.go web/public/templates/httpsms-contacts.csv+git commit -m "chore(api): regenerate swagger for contacts + add CSV import template"+```++---++### Task 10: Regenerate web API TypeScript models++**Files:**+- Modify: `web/shared/types/api.ts` (generated)++**Interfaces:**+- Consumes: `api/docs/swagger.json` (regenerated in Task 9) with the `Contact` schema and `/contacts` paths.+- Produces: generated types `EntitiesContact` and (if the response wrappers were added) `ResponsesContactResponse` / `ResponsesContactsResponse` in `web/shared/types/api.ts`; `EntitiesMessageThread` now includes an optional `contact_details?: EntitiesContact`.++> **Note:** This task must run AFTER Task 9 (swagger regen). No new hand-written code — the model file is generated.++- [ ] **Step 1: Regenerate models**++Run:++```bash+cd web && pnpm api:models+```++Expected: `web/shared/types/api.ts` rewritten with no errors.++- [ ] **Step 2: Verify the Contact type exists**++Run: `cd web && findstr /C:"EntitiesContact" shared\types\api.ts`+Expected: matches for `EntitiesContact` interface and `contact_details` on the message-thread interface.++- [ ] **Step 3: Commit**++```bash+git add web/shared/types/api.ts+git commit -m "chore(web): regenerate API models with Contact types"+```++---++### Task 11: Contacts Pinia store++**Files:**+- Create: `web/app/stores/contacts.ts`++**Interfaces:**+- Consumes: `useApi()` (`apiFetch`), `useNotificationsStore()`, `getApiErrorMessage`, `EntitiesContact` (Task 10).+- Produces: `useContactsStore()` exposing state `contacts`, `loading`, `search`; getters `filteredContacts`, `total`; actions `loadContacts(force?)`, `saveContacts(items)`, `updateContact(id, payload)`, `deleteContact(id)`, `uploadCsv(file)`, `resetState()`.++- [ ] **Step 1: Write the store**++Create `web/app/stores/contacts.ts`:++```ts+import { defineStore } from 'pinia'+import { ref, computed } from 'vue'+import type { EntitiesContact } from '~~/shared/types/api'+import { getApiErrorMessage } from '~/utils/api-error'++export interface ContactInput {+ name: string+ emails: string[]+ phone_numbers: string[]+ properties?: Record<string, string>+}++export const useContactsStore = defineStore('contacts', () => {+ const contacts = ref<EntitiesContact[]>([])+ const loading = ref(false)+ const search = ref('')+ const { apiFetch } = useApi()+ const notificationsStore = useNotificationsStore()++ const total = computed(() => contacts.value.length)++ const filteredContacts = computed<EntitiesContact[]>(() => {+ const term = search.value.trim().toLowerCase()+ if (!term) return contacts.value+ return contacts.value.filter((contact) => {+ const name = (contact.name ?? '').toLowerCase()+ const emails = (contact.emails ?? []).join(' ').toLowerCase()+ const numbers = (contact.phone_numbers ?? []).join(' ').toLowerCase()+ return (+ name.includes(term) ||+ emails.includes(term) ||+ numbers.includes(term)+ )+ })+ })++ async function loadContacts(force = false) {+ if (contacts.value.length > 0 && !force) return+ loading.value = true+ try {+ const response = await apiFetch<{ data: EntitiesContact[] }>(+ '/v1/contacts',+ { params: { limit: 100 } },+ )+ contacts.value = response.data ?? []+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while loading contacts'),+ type: 'error',+ })+ throw error+ } finally {+ loading.value = false+ }+ }++ async function saveContacts(items: ContactInput[]) {+ try {+ await apiFetch('/v1/contacts', { method: 'POST', body: items })+ notificationsStore.addNotification({+ message:+ items.length > 1 ? 'Contacts created' : 'Contact created',+ type: 'success',+ })+ await loadContacts(true)+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while saving contacts'),+ type: 'error',+ })+ throw error+ }+ }++ async function updateContact(id: string, payload: ContactInput) {+ try {+ await apiFetch(`/v1/contacts/${id}`, { method: 'PUT', body: payload })+ notificationsStore.addNotification({+ message: 'Contact updated',+ type: 'success',+ })+ await loadContacts(true)+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while updating contact'),+ type: 'error',+ })+ throw error+ }+ }++ async function deleteContact(id: string) {+ try {+ await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })+ contacts.value = contacts.value.filter((contact) => contact.id !== id)+ notificationsStore.addNotification({+ message: 'Contact deleted',+ type: 'success',+ })+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while deleting contact'),+ type: 'error',+ })+ throw error+ }+ }++ async function uploadCsv(file: File) {+ try {+ const formData = new FormData()+ formData.append('document', file)+ await apiFetch('/v1/contacts/upload', {+ method: 'POST',+ body: formData,+ })+ notificationsStore.addNotification({+ message: 'Contacts imported successfully',+ type: 'success',+ })+ await loadContacts(true)+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while importing contacts'),+ type: 'error',+ })+ throw error+ }+ }++ function resetState() {+ contacts.value = []+ loading.value = false+ search.value = ''+ }++ return {+ contacts,+ loading,+ search,+ total,+ filteredContacts,+ loadContacts,+ saveContacts,+ updateContact,+ deleteContact,+ uploadCsv,+ resetState,+ }+})+```++- [ ] **Step 2: Lint the new store**++Run: `cd web && pnpm lint:js`+Expected: no errors for `app/stores/contacts.ts`.++- [ ] **Step 3: Commit**++```bash+git add web/app/stores/contacts.ts+git commit -m "feat(web): add contacts Pinia store"+```++---++### Task 12: Contacts page with add/edit/delete/import dialogs++**Files:**+- Create: `web/app/pages/contacts/index.vue`++**Interfaces:**+- Consumes: `useContactsStore()` (Task 11), `useFilters()` (`formatPhoneNumber`), `EntitiesContact` (Task 10).+- Produces: the `/contacts` route (Nuxt file-based routing infers `name: 'contacts'`, used by the nav link in Task 13).++**UI requirements (from spec section 7 / reference screenshot):**+- Page title `text-display-large` (NO gradient/glow — theme text only); subtitle showing total contact count.+- Top-right actions: "Import CSV" (outlined button) + "Add Contact" (filled `color="primary"` button).+- Debounced search field filtering by name/email/phone.+- Table of contacts (Name, Emails, Phone Numbers) with edit + delete icon actions per row.+- Add/Edit/Delete/Import are `VDialog`s. **Every `VDialog` MUST set `opacity="0.9"` and its Close button MUST use `color="warning"`.**++- [ ] **Step 1: Write the page**++Create `web/app/pages/contacts/index.vue`:++```vue+<script setup lang="ts">+import {+ mdiArrowLeft,+ mdiPlus,+ mdiFileUpload,+ mdiPencil,+ mdiDelete,+ mdiMagnify,+ mdiClose,+} from '@mdi/js'+import { ref, computed, onMounted } from 'vue'+import type { EntitiesContact } from '~~/shared/types/api'+import { useContactsStore, type ContactInput } from '~/stores/contacts'+import { useFilters } from '~/composables/useFilters'++definePageMeta({+ middleware: ['auth'],+})++useHead({+ title: 'Contacts - httpSMS',+})++const contactsStore = useContactsStore()+const { formatPhoneNumber } = useFilters()++const editDialog = ref(false)+const deleteDialog = ref(false)+const importDialog = ref(false)+const saving = ref(false)+const editingId = ref<string | null>(null)+const pendingDeleteId = ref<string | null>(null)+const importFile = ref<File | null>(null)++const form = ref<{ name: string; emails: string; phone_numbers: string }>({+ name: '',+ emails: '',+ phone_numbers: '',+})++const dialogTitle = computed(() =>+ editingId.value ? 'Edit Contact' : 'Add Contact',+)++function splitList(value: string): string[] {+ return value+ .split(/[,;]/)+ .map((item) => item.trim())+ .filter((item) => item.length > 0)+}++function openAdd() {+ editingId.value = null+ form.value = { name: '', emails: '', phone_numbers: '' }+ editDialog.value = true+}++function openEdit(contact: EntitiesContact) {+ editingId.value = contact.id ?? null+ form.value = {+ name: contact.name ?? '',+ emails: (contact.emails ?? []).join(', '),+ phone_numbers: (contact.phone_numbers ?? []).join(', '),+ }+ editDialog.value = true+}++function openDelete(contact: EntitiesContact) {+ pendingDeleteId.value = contact.id ?? null+ deleteDialog.value = true+}++async function submitForm() {+ saving.value = true+ const payload: ContactInput = {+ name: form.value.name.trim(),+ emails: splitList(form.value.emails),+ phone_numbers: splitList(form.value.phone_numbers),+ }+ try {+ if (editingId.value) {+ await contactsStore.updateContact(editingId.value, payload)+ } else {+ await contactsStore.saveContacts([payload])+ }+ editDialog.value = false+ } catch {+ // notification already surfaced by the store+ } finally {+ saving.value = false+ }+}++async function confirmDelete() {+ if (!pendingDeleteId.value) return+ saving.value = true+ try {+ await contactsStore.deleteContact(pendingDeleteId.value)+ deleteDialog.value = false+ } catch {+ // notification already surfaced by the store+ } finally {+ saving.value = false+ pendingDeleteId.value = null+ }+}++async function submitImport() {+ if (!importFile.value) return+ saving.value = true+ try {+ await contactsStore.uploadCsv(importFile.value)+ importDialog.value = false+ importFile.value = null+ } catch {+ // notification already surfaced by the store+ } finally {+ saving.value = false+ }+}++onMounted(() => {+ contactsStore.loadContacts(true).catch(() => {})+})+</script>++<template>+ <VContainer fluid class="px-0 pt-0">+ <VAppBar>+ <VBtn icon to="/threads">+ <VIcon :icon="mdiArrowLeft" />+ </VBtn>+ <VToolbarTitle>Contacts</VToolbarTitle>+ <VProgressLinear+ :active="contactsStore.loading"+ color="primary"+ :indeterminate="contactsStore.loading"+ location="bottom"+ absolute+ />+ </VAppBar>++ <VContainer>+ <VRow>+ <VCol cols="12" md="10" offset-md="1" xxl="8" offset-xxl="2">+ <div+ class="d-flex flex-column flex-md-row align-md-center mb-6 mt-3"+ >+ <div>+ <h1 class="text-display-large">Contacts</h1>+ <p class="text-medium-emphasis mb-0">+ {{ contactsStore.total }}+ {{ contactsStore.total === 1 ? 'contact' : 'contacts' }}+ </p>+ </div>+ <VSpacer />+ <div class="d-flex mt-4 mt-md-0">+ <VBtn+ variant="outlined"+ color="primary"+ :prepend-icon="mdiFileUpload"+ class="mr-3"+ @click="importDialog = true"+ >+ Import CSV+ </VBtn>+ <VBtn+ color="primary"+ :prepend-icon="mdiPlus"+ @click="openAdd"+ >+ Add Contact+ </VBtn>+ </div>+ </div>++ <VTextField+ v-model="contactsStore.search"+ :prepend-inner-icon="mdiMagnify"+ label="Search contacts"+ variant="outlined"+ density="comfortable"+ clearable+ hide-details+ class="mb-4"+ />++ <VTable density="comfortable">+ <thead>+ <tr class="text-uppercase text-medium-emphasis">+ <th class="text-left">Name</th>+ <th class="text-left">Emails</th>+ <th class="text-left">Phone Numbers</th>+ <th class="text-right">Actions</th>+ </tr>+ </thead>+ <tbody>+ <tr+ v-for="contact in contactsStore.filteredContacts"+ :key="contact.id"+ >+ <td class="text-left">{{ contact.name }}</td>+ <td class="text-left">+ {{ (contact.emails ?? []).join(', ') }}+ </td>+ <td class="text-left">+ {{+ (contact.phone_numbers ?? [])+ .map((number) => formatPhoneNumber(number))+ .join(', ')+ }}+ </td>+ <td class="text-right">+ <VBtn+ icon+ variant="text"+ size="small"+ @click="openEdit(contact)"+ >+ <VIcon :icon="mdiPencil" />+ </VBtn>+ <VBtn+ icon+ variant="text"+ size="small"+ color="error"+ @click="openDelete(contact)"+ >+ <VIcon :icon="mdiDelete" />+ </VBtn>+ </td>+ </tr>+ <tr v-if="contactsStore.filteredContacts.length === 0">+ <td colspan="4" class="text-center text-medium-emphasis py-8">+ No contacts found.+ </td>+ </tr>+ </tbody>+ </VTable>+ </VCol>+ </VRow>+ </VContainer>++ <!-- Add / Edit dialog -->+ <VDialog v-model="editDialog" max-width="560" opacity="0.9">+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>{{ dialogTitle }}</span>+ <VSpacer />+ <VBtn+ icon+ variant="text"+ color="warning"+ @click="editDialog = false"+ >+ <VIcon :icon="mdiClose" />+ </VBtn>+ </VCardTitle>+ <VCardText>+ <VTextField+ v-model="form.name"+ label="Name"+ variant="outlined"+ class="mb-2"+ />+ <VTextField+ v-model="form.emails"+ label="Emails (comma separated)"+ variant="outlined"+ class="mb-2"+ />+ <VTextField+ v-model="form.phone_numbers"+ label="Phone numbers (comma separated)"+ variant="outlined"+ />+ </VCardText>+ <VCardActions>+ <VSpacer />+ <VBtn color="warning" variant="text" @click="editDialog = false">+ Close+ </VBtn>+ <VBtn+ color="primary"+ :loading="saving"+ :disabled="saving"+ @click="submitForm"+ >+ Save+ </VBtn>+ </VCardActions>+ </VCard>+ </VDialog>++ <!-- Delete dialog -->+ <VDialog v-model="deleteDialog" max-width="460" opacity="0.9">+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>Delete Contact</span>+ <VSpacer />+ <VBtn+ icon+ variant="text"+ color="warning"+ @click="deleteDialog = false"+ >+ <VIcon :icon="mdiClose" />+ </VBtn>+ </VCardTitle>+ <VCardText>+ Are you sure you want to delete this contact? This action cannot be+ undone.+ </VCardText>+ <VCardActions>+ <VSpacer />+ <VBtn color="warning" variant="text" @click="deleteDialog = false">+ Close+ </VBtn>+ <VBtn+ color="error"+ :loading="saving"+ :disabled="saving"+ @click="confirmDelete"+ >+ Delete+ </VBtn>+ </VCardActions>+ </VCard>+ </VDialog>++ <!-- Import CSV dialog -->+ <VDialog v-model="importDialog" max-width="560" opacity="0.9">+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>Import Contacts from CSV</span>+ <VSpacer />+ <VBtn+ icon+ variant="text"+ color="warning"+ @click="importDialog = false"+ >+ <VIcon :icon="mdiClose" />+ </VBtn>+ </VCardTitle>+ <VCardText>+ <p class="mb-3">+ Download our+ <a+ class="text-decoration-none hover:text-decoration-underline"+ download+ href="/templates/httpsms-contacts.csv"+ >CSV template</a+ >, fill it in and upload it here. Columns: Name, Emails,+ PhoneNumbers (multiple values separated by ";").+ </p>+ <VFileInput+ v-model="importFile"+ label="CSV file"+ color="primary"+ accept=".csv,text/csv"+ variant="outlined"+ hide-details+ />+ </VCardText>+ <VCardActions>+ <VSpacer />+ <VBtn color="warning" variant="text" @click="importDialog = false">+ Close+ </VBtn>+ <VBtn+ color="primary"+ :loading="saving"+ :disabled="saving || !importFile"+ @click="submitImport"+ >+ Import+ </VBtn>+ </VCardActions>+ </VCard>+ </VDialog>+ </VContainer>+</template>+```++- [ ] **Step 2: Lint the page**++Run: `cd web && pnpm lint:js && pnpm lint:prettier`+Expected: no errors for `app/pages/contacts/index.vue`. If Prettier reports formatting, run `pnpm lintfix` and re-check.++- [ ] **Step 3: Build the site to confirm it compiles**++Run: `cd web && pnpm generate`+Expected: build completes without type errors (the `/contacts` route is emitted).++- [ ] **Step 4: Commit**++```bash+git add web/app/pages/contacts/index.vue+git commit -m "feat(web): add contacts page with add/edit/delete/import dialogs"+```++---++### Task 13: Show contact names on threads + Contacts nav link++**Files:**+- Modify: `web/app/stores/threads.ts` (send `contacts: true`)+- Modify: `web/app/components/MessageThread.vue` (list title + avatar initial)+- Modify: `web/app/pages/threads/[id]/index.vue` (toolbar title)+- Modify: `web/app/components/MessageThreadHeader.vue` (Contacts nav item + icon import)++**Interfaces:**+- Consumes: `EntitiesMessageThread.contact_details?: EntitiesContact` (Task 10), the `/contacts` route (Task 12).+- Produces: no new exports — UI wiring only.++- [ ] **Step 1: Request contact resolution when loading threads**++In `web/app/stores/threads.ts`, add `contacts: true` to the `loadThreads` request params:++```ts+ const response = await apiFetch<{ data: EntitiesMessageThread[] }>(+ '/v1/message-threads',+ {+ params: {+ owner: phonesStore.owner ?? phonesStore.phones[0]?.phone_number,+ limit: 100,+ is_archived: archivedThreads.value,+ contacts: true,+ },+ },+ )+```++- [ ] **Step 2: Show the contact name in the threads list**++In `web/app/components/MessageThread.vue`, replace the list-item title expression:++```vue+ <v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">{{+ thread.contact_details?.name ?? formatPhoneNumber(thread.contact)+ }}</v-list-item-title>+```++And update the avatar initial to prefer the contact name (replace the existing `<template #prepend>` avatar content):++```vue+ <template #prepend>+ <v-avatar+ :color="thread.color"+ size="40"+ :badge="thread.is_read ? false : { color: 'primary', dotSize: 12 }"+ >+ <v-icon+ v-if="!(thread.contact_details?.name || startsWithLetter(thread.contact))"+ color="white"+ >{{ mdiAccount }}</v-icon+ >+ <span v-else class="text-white text-headline-small">{{+ (thread.contact_details?.name ?? thread.contact).substring(0, 1)+ }}</span>+ </v-avatar>+ </template>+```++- [ ] **Step 3: Show the contact name in the thread header**++In `web/app/pages/threads/[id]/index.vue`, replace the toolbar title expression (around line 271):++```vue+ <VToolbarTitle v-if="threadsStore.currentThread">+ {{+ threadsStore.currentThread.contact_details?.name ??+ formatPhoneNumber(threadsStore.currentThread.contact)+ }}+ </VToolbarTitle>+```++- [ ] **Step 4: Add the Contacts navigation item**++In `web/app/components/MessageThreadHeader.vue`, add `mdiAccountMultiple` to the `@mdi/js` import block:++```ts+ mdiCommentTextMultipleOutline,+ mdiAccountMultiple,+ mdiCircle,+```++Add a nav item right after the "Search Messages" `v-list-item` (before the Settings item):++```vue+ <v-list-item :to="{ name: 'contacts' }">+ <template #prepend><v-icon :icon="mdiAccountMultiple" /></template>+ <v-list-item-title>Contacts</v-list-item-title>+ </v-list-item>+```++- [ ] **Step 5: Lint and build**++Run: `cd web && pnpm lint:js && pnpm generate`+Expected: no errors; the build succeeds.++- [ ] **Step 6: Commit**++```bash+git add web/app/stores/threads.ts web/app/components/MessageThread.vue web/app/pages/threads/[id]/index.vue web/app/components/MessageThreadHeader.vue+git commit -m "feat(web): display contact names on threads and add Contacts nav link"+```++---++## Final Verification++- [ ] **API full test + build**++```bash+cd api && go test -vet=off ./... && go build ./...+```+Expected: all packages pass; build succeeds.++- [ ] **Web lint + build**++```bash+cd web && pnpm lint && pnpm generate+```+Expected: lint clean; static build succeeds.++- [ ] **Manual smoke test (optional, with Docker stack)**++```bash+docker compose up --build+```+Then: create a contact via `POST /v1/contacts`, load `/threads` and confirm the contact name shows for a matching phone number; open `/contacts` and exercise add/edit/delete/import.diff --git a/docs/superpowers/specs/2026-08-21-contact-phone-input-design.md b/docs/superpowers/specs/2026-08-21-contact-phone-input-design.mdnew file mode 100644index 00000000..2bca6d00--- /dev/null+++ b/docs/superpowers/specs/2026-08-21-contact-phone-input-design.md@@ -0,0 +1,29 @@+# Contact Phone Input Design++## Goal++Use the existing `v-phone-input` component for phone numbers in the contact+add/edit dialog.++## Design++Represent each form phone row with a phone number value and its own country.+Bind those fields to `v-phone-input` using `v-model` and `v-model:country`,+following the messages page configuration.++Existing E.164 phone numbers derive their country with `libphonenumber-js`.+Numbers without a detectable country and newly added rows default to `US`.+Removing a row removes both its number and country because they are stored in+one object.++## Behavior++- Keep support for multiple phone numbers.+- Preserve current required-phone validation and server error display.+- Submit only trimmed, non-empty phone number values to the API.+- Keep add, edit, and remove behavior unchanged apart from the country-aware+ input.++## Validation++Run ESLint, Stylelint, and Prettier against the changed contact page.diff --git a/docs/superpowers/specs/2026-08-21-contacts-table-header-design.md b/docs/superpowers/specs/2026-08-21-contacts-table-header-design.mdnew file mode 100644index 00000000..afa59dfd--- /dev/null+++ b/docs/superpowers/specs/2026-08-21-contacts-table-header-design.md@@ -0,0 +1,29 @@+# Contacts Table Header Styling Design++## Goal++Make every header in the contacts data table uppercase and grey using Vuetify's+standard text utility classes.++## Design++Add the `headers` slot to the existing `VDataTableServer` in+`web/app/pages/contacts/index.vue`. Render each header title with+`text-uppercase text-medium-emphasis` while retaining Vuetify's existing header+layout and per-column alignment.++This approach keeps presentation in the template, avoids brittle selectors+against Vuetify internals, and leaves the header definitions and table data flow+unchanged.++## Scope++- Apply the styling to Name, Phone Numbers, Emails, Created, Updated, and+ Actions.+- Preserve the existing data, pagination, loading, and item slot behavior.+- Do not introduce component-level CSS or change the displayed header labels.++## Validation++Run the existing web lint command and confirm the contacts page template passes+Vue and TypeScript validation.diff --git a/tests/.env.test b/tests/.env.testindex 78bb614b..c4c1e3ef 100644--- a/tests/.env.test+++ b/tests/.env.test@@ -30,4 +30,5 @@ GCS_BUCKET_NAME=UPTRACE_DSN=CLOUDFLARE_TURNSTILE_SECRET_KEY=HEARTBEAT_DB_BACKEND=mongodb+CONTACT_DB_BACKEND=mongodbMONGODB_URI=mongodb://httpsms:testpassword@mongodb:27017/?authSource=admin&appName=httpsmsdiff --git a/tests/README.md b/tests/README.mdindex 45bbb278..20e4f5e1 100644--- a/tests/README.md+++ b/tests/README.md@@ -55,6 +55,7 @@ The API's Firebase SDK is configured (via `FCM_ENDPOINT` env var) to redirect al- [x] **Receive SMS E2E** — Phone submits received message to API → message is stored and retrievable via GET endpoint- [x] **Message thread read receipts E2E** — Incoming SMS and missed calls mark a thread unread, the existing thread update endpoint marks it read, and outbound activity preserves unread state- [x] **Unarchive Thread on Receive E2E** — Archived thread returns to the inbox on inbound message when the phone's `unarchive_thread` setting is enabled, and stays archived when disabled+- [x] **Contacts E2E** — JSON CRUD, search and pagination totals, CSV import normalization, and contact details attached to message threads## Prerequisitesdiff --git a/tests/contacts_integration_test.go b/tests/contacts_integration_test.gonew file mode 100644index 00000000..2dcd4d5c--- /dev/null+++ b/tests/contacts_integration_test.go@@ -0,0 +1,332 @@+package tests++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "io"+ "mime/multipart"+ "net/http"+ "net/url"+ "strings"+ "testing"+ "time"++ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++type integrationContact struct {+ ID string `json:"id"`+ Name string `json:"name"`+ Emails []string `json:"emails"`+ PhoneNumbers []string `json:"phone_numbers"`+ Properties map[string]string `json:"properties"`+}++type integrationContactsResponse struct {+ Data []integrationContact `json:"data"`+ Total int64 `json:"total"`+}++type integrationContactResponse struct {+ Data integrationContact `json:"data"`+}++type integrationContactThread struct {+ ID string `json:"id"`+ Contact string `json:"contact"`+ ContactDetails *integrationContact `json:"contact_details"`+}++func createIntegrationContacts(+ ctx context.Context,+ t *testing.T,+ contacts []map[string]any,+) []integrationContact {+ t.Helper()++ var response integrationContactsResponse+ requestJSON(+ ctx,+ t,+ http.MethodPost,+ "/v1/contacts",+ userAPIKey,+ contacts,+ http.StatusCreated,+ &response,+ )+ require.Len(t, response.Data, len(contacts))+ return response.Data+}++func deleteIntegrationContact(ctx context.Context, t *testing.T, contactID string) {+ t.Helper()++ requestJSON(+ ctx,+ t,+ http.MethodDelete,+ "/v1/contacts/"+contactID,+ userAPIKey,+ nil,+ http.StatusNoContent,+ nil,+ )+}++func cleanupIntegrationContact(t *testing.T, contactID string) {+ t.Helper()++ request, err := http.NewRequest(+ http.MethodDelete,+ apiBaseURL+"/v1/contacts/"+contactID,+ nil,+ )+ require.NoError(t, err)+ request.Header.Set("x-api-key", userAPIKey)++ response, err := http.DefaultClient.Do(request)+ require.NoError(t, err)+ defer response.Body.Close()++ responseBody, err := io.ReadAll(response.Body)+ require.NoError(t, err)+ require.Contains(+ t,+ []int{http.StatusNoContent, http.StatusNotFound},+ response.StatusCode,+ "response: %s",+ string(responseBody),+ )+}++func listIntegrationContacts(+ ctx context.Context,+ t *testing.T,+ query string,+ skip int,+ limit int,+) integrationContactsResponse {+ t.Helper()++ path := fmt.Sprintf(+ "/v1/contacts?query=%s&skip=%d&limit=%d",+ url.QueryEscape(query),+ skip,+ limit,+ )+ var response integrationContactsResponse+ requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)+ return response+}++func uploadIntegrationContactsCSV(+ ctx context.Context,+ t *testing.T,+ contents string,+) integrationContactsResponse {+ t.Helper()++ var body bytes.Buffer+ writer := multipart.NewWriter(&body)+ part, err := writer.CreateFormFile("document", "contacts.csv")+ require.NoError(t, err)+ _, err = part.Write([]byte(contents))+ require.NoError(t, err)+ require.NoError(t, writer.Close())++ request, err := http.NewRequestWithContext(+ ctx,+ http.MethodPost,+ apiBaseURL+"/v1/contacts/upload",+ &body,+ )+ require.NoError(t, err)+ request.Header.Set("x-api-key", userAPIKey)+ request.Header.Set("Content-Type", writer.FormDataContentType())++ response, err := http.DefaultClient.Do(request)+ require.NoError(t, err)+ defer response.Body.Close()++ responseBody, err := io.ReadAll(response.Body)+ require.NoError(t, err)+ require.Equal(t, http.StatusCreated, response.StatusCode, "response: %s", string(responseBody))++ var result integrationContactsResponse+ require.NoError(t, json.Unmarshal(responseBody, &result))+ return result+}++func waitForThreadWithContact(+ ctx context.Context,+ t *testing.T,+ owner string,+ phoneNumber string,+ timeout time.Duration,+) integrationContactThread {+ t.Helper()++ deadline := time.Now().Add(timeout)+ for time.Now().Before(deadline) {+ path := fmt.Sprintf(+ "/v1/message-threads?owner=%s&contacts=true&skip=0&limit=20",+ url.QueryEscape(owner),+ )+ var response struct {+ Data []integrationContactThread `json:"data"`+ }+ requestJSON(ctx, t, http.MethodGet, path, userAPIKey, nil, http.StatusOK, &response)+ for _, thread := range response.Data {+ if thread.Contact == phoneNumber && thread.ContactDetails != nil {+ return thread+ }+ }+ time.Sleep(500 * time.Millisecond)+ }++ t.Fatalf("thread for %s did not include contact details within %v", phoneNumber, timeout)+ return integrationContactThread{}+}++func TestContacts_CRUDSearchAndPagination(t *testing.T) {+ ctx := context.Background()+ marker := strings.ToLower(uuid.New().String())+ firstPhone := randomPhoneNumber()+ secondPhone := randomPhoneNumber()++ created := createIntegrationContacts(ctx, t, []map[string]any{+ {+ "name": " Alice " + marker + " ",+ "emails": []string{" ALICE-" + marker + "@EXAMPLE.COM "},+ "phone_numbers": []string{strings.TrimPrefix(firstPhone, "+")},+ "properties": map[string]string{"company": "Acme"},+ },+ {+ "name": "Bob " + marker,+ "emails": []string{"bob-" + marker + "@example.com"},+ "phone_numbers": []string{secondPhone},+ },+ })+ for _, contact := range created {+ contactID := contact.ID+ t.Cleanup(func() {+ cleanupIntegrationContact(t, contactID)+ })+ }++ require.Len(t, created, 2)+ assert.Equal(t, "Alice "+marker, created[0].Name)+ assert.Equal(t, []string{"alice-" + marker + "@example.com"}, created[0].Emails)+ assert.Equal(t, []string{firstPhone}, created[0].PhoneNumbers)+ assert.Equal(t, map[string]string{"company": "Acme"}, created[0].Properties)++ page := listIntegrationContacts(ctx, t, marker, 0, 1)+ assert.EqualValues(t, 2, page.Total)+ require.Len(t, page.Data, 1)++ emailMatch := listIntegrationContacts(ctx, t, "ALICE-"+marker+"@EXAMPLE.COM", 0, 20)+ assert.EqualValues(t, 1, emailMatch.Total)+ require.Len(t, emailMatch.Data, 1)+ assert.Equal(t, created[0].ID, emailMatch.Data[0].ID)++ var updated integrationContactResponse+ requestJSON(+ ctx,+ t,+ http.MethodPut,+ "/v1/contacts/"+created[0].ID,+ userAPIKey,+ map[string]any{+ "name": "Updated " + marker,+ "emails": []string{"updated-" + marker + "@example.com"},+ "phone_numbers": []string{firstPhone},+ "properties": map[string]string{"company": "NdoleStudio"},+ },+ http.StatusOK,+ &updated,+ )+ assert.Equal(t, "Updated "+marker, updated.Data.Name)+ assert.Equal(t, []string{"updated-" + marker + "@example.com"}, updated.Data.Emails)+ assert.Equal(t, map[string]string{"company": "NdoleStudio"}, updated.Data.Properties)++ deleteIntegrationContact(ctx, t, created[0].ID)++ deletedMatch := listIntegrationContacts(ctx, t, "updated-"+marker+"@example.com", 0, 20)+ assert.Zero(t, deletedMatch.Total)+ assert.Empty(t, deletedMatch.Data)+}++func TestContacts_CSVUpload(t *testing.T) {+ ctx := context.Background()+ marker := strings.ToLower(uuid.New().String())+ phoneNumber := randomPhoneNumber()+ csv := fmt.Sprintf(+ "Name,Emails,PhoneNumbers\nCSV %s,\"FIRST-%[email protected];second-%[email protected]\",%s\n",+ marker,+ marker,+ marker,+ strings.TrimPrefix(phoneNumber, "+"),+ )++ response := uploadIntegrationContactsCSV(ctx, t, csv)+ require.Len(t, response.Data, 1)+ contact := response.Data[0]+ t.Cleanup(func() {+ cleanupIntegrationContact(t, contact.ID)+ })++ assert.Equal(t, "CSV "+marker, contact.Name)+ assert.Equal(t, []string{+ "first-" + marker + "@example.com",+ "second-" + marker + "@example.com",+ }, contact.Emails)+ assert.Equal(t, []string{phoneNumber}, contact.PhoneNumbers)++ listed := listIntegrationContacts(ctx, t, marker, 0, 20)+ assert.EqualValues(t, 1, listed.Total)+ require.Len(t, listed.Data, 1)+ assert.Equal(t, contact.ID, listed.Data[0].ID)+}++func TestContacts_MessageThreadsIncludeContactDetails(t *testing.T) {+ ctx := context.Background()+ phone := setupPhone(ctx, t, 60)+ contactPhone := randomPhoneNumber()+ marker := strings.ToLower(uuid.New().String())++ created := createIntegrationContacts(ctx, t, []map[string]any{+ {+ "name": "Thread Contact " + marker,+ "emails": []string{"thread-" + marker + "@example.com"},+ "phone_numbers": []string{contactPhone},+ "properties": map[string]string{"source": "integration-test"},+ },+ })+ contact := created[0]+ t.Cleanup(func() {+ cleanupIntegrationContact(t, contact.ID)+ })++ messageID := receiveInbound(+ ctx,+ t,+ phone.PhoneAPIKey,+ contactPhone,+ phone.PhoneNumber,+ "Contact enrichment "+marker,+ time.Now(),+ )+ pollMessageStatus(ctx, t, messageID, "received", 15*time.Second)++ thread := waitForThreadWithContact(ctx, t, phone.PhoneNumber, contactPhone, 20*time.Second)+ require.NotNil(t, thread.ContactDetails)+ assert.Equal(t, contact.ID, thread.ContactDetails.ID)+ assert.Equal(t, contact.Name, thread.ContactDetails.Name)+ assert.Equal(t, contact.PhoneNumbers, thread.ContactDetails.PhoneNumbers)+ assert.Equal(t, contact.Properties, thread.ContactDetails.Properties)+}diff --git a/tests/helpers_test.go b/tests/helpers_test.goindex 49a7a654..dfbf2885 100644--- a/tests/helpers_test.go+++ b/tests/helpers_test.go@@ -110,6 +110,8 @@ func setupPhone(ctx context.Context, t *testing.T, messagesPerMinute uint) testPrequire.NoError(t, err)require.Equal(t, http.StatusOK, resp.HTTPResponse.StatusCode, "fcm token bind failed")+ waitForPhoneAuthorization(ctx, t, phoneAPIKeyValue, phoneNumber, 20*time.Second)+return testPhone{PhoneNumber: phoneNumber,PhoneAPIKey: phoneAPIKeyValue,@@ -117,6 +119,55 @@ func setupPhone(ctx context.Context, t *testing.T, messagesPerMinute uint) testP}}+func waitForPhoneAuthorization(+ ctx context.Context,+ t *testing.T,+ phoneAPIKey string,+ phoneNumber string,+ timeout time.Duration,+) {+ t.Helper()++ body, err := json.Marshal(map[string]interface{}{+ "phone_numbers": []string{phoneNumber},+ "charging": true,+ })+ require.NoError(t, err)++ var responseBody []byte+ var statusCode int+ deadline := time.Now().Add(timeout)+ for time.Now().Before(deadline) {+ request, requestErr := http.NewRequestWithContext(+ ctx,+ http.MethodPost,+ apiBaseURL+"/v1/heartbeats",+ bytes.NewReader(body),+ )+ require.NoError(t, requestErr)+ request.Header.Set("Content-Type", "application/json")+ request.Header.Set("x-api-key", phoneAPIKey)++ response, requestErr := http.DefaultClient.Do(request)+ require.NoError(t, requestErr)+ responseBody, requestErr = io.ReadAll(response.Body)+ response.Body.Close()+ require.NoError(t, requestErr)++ statusCode = response.StatusCode+ if statusCode == http.StatusCreated {+ return+ }+ if statusCode != http.StatusUnauthorized {+ require.Equal(t, http.StatusCreated, statusCode, "phone authorization check failed: %s", string(responseBody))+ }++ time.Sleep(500 * time.Millisecond)+ }++ require.Equal(t, http.StatusCreated, statusCode, "phone authorization was not ready within %v: %s", timeout, string(responseBody))+}+func setupWebhook(ctx context.Context, t *testing.T, phoneNumber string, events []string) (signingKey string, webhookPath string) {t.Helper()diff --git a/tests/integration_test.go b/tests/integration_test.goindex 66abecdd..7cc16809 100644--- a/tests/integration_test.go+++ b/tests/integration_test.go@@ -56,7 +56,7 @@ func TestSendSMS_Encrypted(t *testing.T) {assert.NotEqual(t, plaintext, outstanding["content"])fireEvent(ctx, t, phone.PhoneAPIKey, messageID, "SENT")- time.Sleep(200 * time.Millisecond)+ pollMessageStatus(ctx, t, messageID, "sent", 15*time.Second)fireEvent(ctx, t, phone.PhoneAPIKey, messageID, "DELIVERED")msg := pollMessageStatus(ctx, t, messageID, "delivered", 30*time.Second)@@ -200,8 +200,10 @@ func TestSendSMS_RateLimit(t *testing.T) {assert.GreaterOrEqual(t, gapMs, int64(5500), "rate limit gap should be >= 5500ms (6s minus timing tolerance), got %dms", gapMs)fireEvent(ctx, t, phone.PhoneAPIKey, msgID1, "SENT")- fireEvent(ctx, t, phone.PhoneAPIKey, msgID1, "DELIVERED")+ pollMessageStatus(ctx, t, msgID1, "sent", 15*time.Second)fireEvent(ctx, t, phone.PhoneAPIKey, msgID2, "SENT")+ pollMessageStatus(ctx, t, msgID2, "sent", 15*time.Second)+ fireEvent(ctx, t, phone.PhoneAPIKey, msgID1, "DELIVERED")fireEvent(ctx, t, phone.PhoneAPIKey, msgID2, "DELIVERED")msg1 := pollMessageStatus(ctx, t, msgID1, "delivered", 15*time.Second)@@ -335,7 +337,7 @@ func TestSendSMS_OutstandingFlow(t *testing.T) {assert.Equal(t, contactNumber, outstanding["contact"])fireEvent(ctx, t, phone.PhoneAPIKey, messageID, "SENT")- time.Sleep(200 * time.Millisecond)+ pollMessageStatus(ctx, t, messageID, "sent", 15*time.Second)fireEvent(ctx, t, phone.PhoneAPIKey, messageID, "DELIVERED")msg := pollMessageStatus(ctx, t, messageID, "delivered", 30*time.Second)@@ -538,7 +540,7 @@ func TestBulkSMS_Excel(t *testing.T) {// Fire SENT then DELIVERED on message 1, leave message 2 pendingfireEvent(ctx, t, phone.PhoneAPIKey, msgID1, "SENT")- time.Sleep(200 * time.Millisecond)+ pollMessageStatus(ctx, t, msgID1, "sent", 15*time.Second)fireEvent(ctx, t, phone.PhoneAPIKey, msgID1, "DELIVERED")// Poll until message 1 reaches "delivered"diff --git a/web/app/components/ContactDialog.vue b/web/app/components/ContactDialog.vuenew file mode 100644index 00000000..2df329a9--- /dev/null+++ b/web/app/components/ContactDialog.vue@@ -0,0 +1,411 @@+<script setup lang="ts">+import {+ mdiAccount,+ mdiAlertCircleOutline,+ mdiClose,+ mdiContentSaveCheck,+ mdiEmailOutline,+ mdiPlus,+} from '@mdi/js'+import { parsePhoneNumberFromString } from 'libphonenumber-js'+import type { EntitiesContact } from '~~/shared/types/api'+import { useContactsStore, type ContactInput } from '~/stores/contacts'+import { toApiError } from '~/utils/api-error'+import { ErrorMessages } from '~/utils/errors'++interface PropertyRow {+ key: string+ value: string+}++interface PhoneNumberRow {+ value: string+ country: string+}++interface ContactForm {+ name: string+ phoneNumbers: PhoneNumberRow[]+ emails: string[]+ properties: PropertyRow[]+}++const props = withDefaults(+ defineProps<{+ modelValue: boolean+ contact?: EntitiesContact | null+ initialPhoneNumber?: string+ refreshContacts?: boolean+ }>(),+ {+ contact: null,+ initialPhoneNumber: '',+ refreshContacts: true,+ },+)++const emit = defineEmits<{+ saved: []+ 'update:modelValue': [value: boolean]+}>()++const contactsStore = useContactsStore()+const saving = ref(false)+const form = ref<ContactForm>(emptyForm())+const formErrors = ref(new ErrorMessages())++const dialogTitle = computed(() =>+ props.contact ? 'Edit Contact' : 'Add Contact',+)++function phoneNumberRow(value = ''): PhoneNumberRow {+ return {+ value,+ country: parsePhoneNumberFromString(value)?.country ?? 'US',+ }+}++function emptyForm(): ContactForm {+ return {+ name: '',+ phoneNumbers: [phoneNumberRow(props?.initialPhoneNumber)],+ emails: [''],+ properties: [{ key: '', value: '' }],+ }+}++function resetForm() {+ const contact = props.contact+ if (!contact) {+ form.value = emptyForm()+ } else {+ const propertyEntries = Object.entries(contact.properties ?? {}).map(+ ([key, value]) => ({ key, value }),+ )+ form.value = {+ name: contact.name ?? '',+ phoneNumbers: contact.phone_numbers?.length+ ? contact.phone_numbers.map((value) => phoneNumberRow(value))+ : [phoneNumberRow()],+ emails: contact.emails?.length ? [...contact.emails] : [''],+ properties: propertyEntries.length+ ? propertyEntries+ : [{ key: '', value: '' }],+ }+ }+ formErrors.value = new ErrorMessages()+}++function closeDialog() {+ emit('update:modelValue', false)+}++function addPhoneNumber() {+ form.value.phoneNumbers.push(phoneNumberRow())+}++function removePhoneNumber(index: number) {+ form.value.phoneNumbers.splice(index, 1)+ if (form.value.phoneNumbers.length === 0) {+ form.value.phoneNumbers.push(phoneNumberRow())+ }+}++function addEmail() {+ form.value.emails.push('')+}++function removeEmail(index: number) {+ form.value.emails.splice(index, 1)+ if (form.value.emails.length === 0) {+ form.value.emails.push('')+ }+}++function addProperty() {+ form.value.properties.push({ key: '', value: '' })+}++function removeProperty(index: number) {+ form.value.properties.splice(index, 1)+ if (form.value.properties.length === 0) {+ form.value.properties.push({ key: '', value: '' })+ }+}++function buildPayload(): ContactInput {+ const properties: Record<string, string> = {}+ form.value.properties.forEach((row) => {+ const key = row.key.trim()+ if (key) {+ properties[key] = row.value+ }+ })+ return {+ name: form.value.name.trim(),+ phone_numbers: form.value.phoneNumbers+ .map(({ value }) => value.trim())+ .filter((value) => value.length > 0),+ emails: form.value.emails+ .map((value) => value.trim())+ .filter((value) => value.length > 0),+ properties,+ }+}++function validateForm(): boolean {+ const bag = new ErrorMessages()+ if (form.value.name.trim() === '') {+ bag.add('name', 'The name is required.')+ }+ const hasPhone = form.value.phoneNumbers.some(+ ({ value }) => value.trim().length > 0,+ )+ if (!hasPhone) {+ bag.add('phone_numbers', 'At least one phone number is required.')+ }+ formErrors.value = bag+ return bag.size() === 0+}++function fieldErrorsFromApi(error: unknown): string[] {+ const data = toApiError(error).data?.data+ if (!data || typeof data !== 'object') {+ return []+ }+ return Object.values(data).flat()+}++async function submitForm() {+ if (!validateForm()) {+ return+ }+ const payload = buildPayload()+ saving.value = true+ try {+ if (props.contact) {+ await contactsStore.updateContact(props.contact.id, payload, {+ refresh: props.refreshContacts,+ })+ } else {+ await contactsStore.saveContacts([payload], {+ refresh: props.refreshContacts,+ })+ }+ closeDialog()+ emit('saved')+ } catch (error: unknown) {+ const bag = new ErrorMessages()+ const messages = fieldErrorsFromApi(error)+ if (messages.length > 0) {+ bag.addMany('contacts', messages)+ }+ formErrors.value = bag+ } finally {+ saving.value = false+ }+}++watch(+ () => props.modelValue,+ (isOpen) => {+ if (isOpen) {+ resetForm()+ }+ },+ { immediate: true },+)+</script>++<template>+ <VDialog+ :model-value="modelValue"+ max-width="640"+ opacity="0.9"+ @update:model-value="emit('update:modelValue', $event)"+ >+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>{{ dialogTitle }}</span>+ <VSpacer />+ <VBtn+ :icon="mdiClose"+ variant="text"+ color="warning"+ size="small"+ aria-label="Close dialog"+ @click="closeDialog"+ />+ </VCardTitle>+ <VCardText>+ <VAlert+ v-if="formErrors.get('contacts').length"+ type="error"+ variant="tonal"+ density="comfortable"+ class="mb-4"+ :icon="mdiAlertCircleOutline"+ >+ <ul class="pl-4 mb-0">+ <li v-for="message in formErrors.get('contacts')" :key="message">+ {{ message }}+ </li>+ </ul>+ </VAlert>++ <VTextField+ v-model="form.name"+ label="Name"+ variant="outlined"+ density="comfortable"+ persistent-placeholder+ placeholder="e.g John Doe"+ :prepend-inner-icon="mdiAccount"+ :error="formErrors.has('name')"+ :error-messages="formErrors.get('name')"+ class="mb-2"+ />++ <div class="d-flex align-center mt-2 mb-1">+ <span class="text-subtitle-2">Phone Numbers</span>+ <VSpacer />+ <VBtn+ variant="text"+ color="primary"+ size="small"+ :prepend-icon="mdiPlus"+ @click="addPhoneNumber"+ >+ Add+ </VBtn>+ </div>+ <div+ v-for="(phone, index) in form.phoneNumbers"+ :key="`phone-${index}`"+ class="d-flex align-start ga-2"+ >+ <div class="mt-2" style="flex: 0 0 92%">+ <v-phone-input+ v-model="phone.value"+ v-model:country="phone.country"+ :label="`Phone number ${index + 1}`"+ country-label="Country"+ placeholder="Phone number e.g 18005550199"+ variant="outlined"+ density="comfortable"+ color="primary"+ persistent-placeholder+ :error="index === 0 && formErrors.has('phone_numbers')"+ :error-messages="+ index === 0 ? formErrors.get('phone_numbers') : []+ "+ />+ </div>+ <div style="flex: 0 0 8%">+ <VBtn+ :icon="mdiClose"+ variant="text"+ size="small"+ class="mt-1"+ aria-label="Remove phone number"+ @click="removePhoneNumber(index)"+ />+ </div>+ </div>++ <div class="d-flex align-center mt-2 mb-1">+ <span class="text-subtitle-2">Email Addresses</span>+ <VSpacer />+ <VBtn+ variant="text"+ color="primary"+ size="small"+ :prepend-icon="mdiPlus"+ @click="addEmail"+ >+ Add+ </VBtn>+ </div>+ <div+ v-for="(email, index) in form.emails"+ :key="`email-${email}-${index}`"+ class="d-flex align-start ga-2"+ >+ <VTextField+ v-model="form.emails[index]"+ :label="`Email ${index + 1}`"+ placeholder="e.g [email protected]"+ variant="outlined"+ autocomplete="email"+ type="email"+ persistent-placeholder+ density="comfortable"+ :prepend-inner-icon="mdiEmailOutline"+ />+ <VBtn+ :icon="mdiClose"+ variant="text"+ size="small"+ class="mt-1"+ aria-label="Remove email"+ @click="removeEmail(index)"+ />+ </div>++ <div class="d-flex align-center mt-2 mb-1">+ <span class="text-subtitle-2">Properties</span>+ <VSpacer />+ <VBtn+ variant="text"+ color="primary"+ size="small"+ :prepend-icon="mdiPlus"+ @click="addProperty"+ >+ Add+ </VBtn>+ </div>+ <div+ v-for="(property, index) in form.properties"+ :key="`property-${index}`"+ class="d-flex align-start ga-2"+ >+ <VTextField+ v-model="property.key"+ label="Key"+ variant="outlined"+ density="comfortable"+ />+ <VTextField+ v-model="property.value"+ label="Value"+ variant="outlined"+ density="comfortable"+ />+ <VBtn+ :icon="mdiClose"+ variant="text"+ size="small"+ class="mt-1"+ aria-label="Remove property"+ @click="removeProperty(index)"+ />+ </div>+ </VCardText>+ <VCardActions class="pb-4">+ <VBtn+ color="primary"+ variant="flat"+ :loading="saving"+ :disabled="saving"+ :prepend-icon="mdiContentSaveCheck"+ @click="submitForm"+ >+ Save Contact+ </VBtn>+ <VSpacer />+ <VBtn color="warning" variant="text" @click="closeDialog">Close</VBtn>+ </VCardActions>+ </VCard>+ </VDialog>+</template>diff --git a/web/app/components/MessageThread.vue b/web/app/components/MessageThread.vueindex 2a983431..d62eeb09 100644--- a/web/app/components/MessageThread.vue+++ b/web/app/components/MessageThread.vue@@ -7,12 +7,13 @@ import {mdiAlert,mdiAccount,} from '@mdi/js'-import { formatPhoneNumber, startsWithLetter } from '~/utils/filters'+import type { EntitiesMessageThread } from '~~/shared/types/api'const threadsStore = useThreadsStore()const phonesStore = usePhonesStore()const appStore = useAppStore()const notificationsStore = useNotificationsStore()+const { formatPhoneNumber, startsWithLetter } = useFilters()function threadDate(date: string): string {return new Date(date).toLocaleString(undefined, {@@ -27,6 +28,21 @@ function onInstallApp() {message: 'Downloading the httpSMS Android App',})}++function threadContactName(thread: EntitiesMessageThread): string {+ return thread.contact_details?.name?.trim() ?? ''+}++function threadContactTitle(thread: EntitiesMessageThread): string {+ return threadContactName(thread) || formatPhoneNumber(thread.contact)+}++function threadAvatarInitial(thread: EntitiesMessageThread): string {+ const contactName = threadContactName(thread)+ if (contactName) return contactName.substring(0, 1)++ return startsWithLetter(thread.contact) ? thread.contact.substring(0, 1) : ''+}</script><template>@@ -104,16 +120,16 @@ function onInstallApp() {size="40":badge="thread.is_read ? false : { color: 'primary', dotSize: 12 }">- <v-icon v-if="!startsWithLetter(thread.contact)" color="white">{{+ <v-icon v-if="!threadAvatarInitial(thread)" color="white">{{mdiAccount}}</v-icon><span v-else class="text-white text-headline-small">{{- thread.contact.substring(0, 1)+ threadAvatarInitial(thread)}}</span></v-avatar></template><v-list-item-title :class="{ 'font-weight-bold': !thread.is_read }">{{- formatPhoneNumber(thread.contact)+ threadContactTitle(thread)}}</v-list-item-title><v-list-item-subtitleclass="text-truncate mt-1"diff --git a/web/app/components/MessageThreadHeader.vue b/web/app/components/MessageThreadHeader.vueindex 1e1a81eb..12917b59 100644--- a/web/app/components/MessageThreadHeader.vue+++ b/web/app/components/MessageThreadHeader.vue@@ -14,9 +14,9 @@ import {mdiDotsVertical,mdiMagnify,mdiCommentTextMultipleOutline,+ mdiAccountMultiple,mdiCircle,} from '@mdi/js'-import { formatPhoneNumber, phoneCountry, humanizeTime } from '~/utils/filters'import type { EntitiesPhone } from '~~/shared/types/api'const router = useRouter()@@ -28,6 +28,7 @@ const threadsStore = useThreadsStore()const appStore = useAppStore()const notificationsStore = useNotificationsStore()const redirectPreferenceStore = useRedirectPreferenceStore()+const { formatPhoneNumber, phoneCountry, humanizeTime } = useFilters()const selectedMenuItem = ref(-1)@@ -180,6 +181,10 @@ async function logout() {<template #prepend><v-icon :icon="mdiMagnify" /></template><v-list-item-title>Search Messages</v-list-item-title></v-list-item>+ <v-list-item :to="{ name: 'contacts' }">+ <template #prepend><v-icon :icon="mdiAccountMultiple" /></template>+ <v-list-item-title>Contacts</v-list-item-title>+ </v-list-item><v-list-item :to="{ name: 'settings' }"><template #prepend><v-icon :icon="mdiAccountCog" /></template><v-list-item-title>Settings</v-list-item-title>diff --git a/web/app/composables/useFilters.ts b/web/app/composables/useFilters.tsindex c84157ea..2b54bbb4 100644--- a/web/app/composables/useFilters.ts+++ b/web/app/composables/useFilters.ts@@ -7,6 +7,8 @@ import {formatBillingPeriod,formatBillingPeriodDateOrdinal,humanizeTime,+ humanizeTimeShort,+ startsWithLetter,} from '../utils/filters'import { capitalize } from '../utils/capitalize'@@ -18,8 +20,10 @@ export function useFilters() {formatMoney,formatDecimal,formatBillingPeriod,+ humanizeTimeShort,formatBillingPeriodDateOrdinal,humanizeTime,+ startsWithLetter,capitalize,}}diff --git a/web/app/pages/billing/index.vue b/web/app/pages/billing/index.vueindex 555bd129..c5af811e 100644--- a/web/app/pages/billing/index.vue+++ b/web/app/pages/billing/index.vue@@ -27,7 +27,7 @@ useHead({})const config = useRuntimeConfig()-const { lgAndUp } = useDisplay()+const { lgAndUp } = useVDisplay()const authStore = useAuthStore()const billingStore = useBillingStore()const notificationsStore = useNotificationsStore()diff --git a/web/app/pages/blog/end-to-end-encryption-to-sms-messages.vue b/web/app/pages/blog/end-to-end-encryption-to-sms-messages.vueindex 5e7e0a6f..bda47bca 100644--- a/web/app/pages/blog/end-to-end-encryption-to-sms-messages.vue+++ b/web/app/pages/blog/end-to-end-encryption-to-sms-messages.vue@@ -1,10 +1,8 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'-import { mdiLanguageGo, mdiLanguageJavascript } from '@mdi/js'import { ref } from 'vue'-const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()const encryptTab = ref('javascript')const sendTab = ref('javascript')diff --git a/web/app/pages/blog/forward-incoming-sms-from-phone-to-webhook.vue b/web/app/pages/blog/forward-incoming-sms-from-phone-to-webhook.vueindex d7f17c78..dd0306b6 100644--- a/web/app/pages/blog/forward-incoming-sms-from-phone-to-webhook.vue+++ b/web/app/pages/blog/forward-incoming-sms-from-phone-to-webhook.vue@@ -1,7 +1,5 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'--const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/blog/grant-send-and-read-sms-permissions-on-android.vue b/web/app/pages/blog/grant-send-and-read-sms-permissions-on-android.vueindex 0261aea9..e953aaca 100644--- a/web/app/pages/blog/grant-send-and-read-sms-permissions-on-android.vue+++ b/web/app/pages/blog/grant-send-and-read-sms-permissions-on-android.vue@@ -1,8 +1,7 @@<script setup lang="ts">import { mdiDotsVertical } from '@mdi/js'-import { useDisplay } from 'vuetify'-const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/blog/how-to-send-sms-messages-from-excel.vue b/web/app/pages/blog/how-to-send-sms-messages-from-excel.vueindex eb010ce0..f55f922a 100644--- a/web/app/pages/blog/how-to-send-sms-messages-from-excel.vue+++ b/web/app/pages/blog/how-to-send-sms-messages-from-excel.vue@@ -1,9 +1,7 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'-import { mdiCommentTextMultipleOutline } from '@mdi/js'-const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/blog/index.vue b/web/app/pages/blog/index.vueindex 9516b43f..ec1a620c 100644--- a/web/app/pages/blog/index.vue+++ b/web/app/pages/blog/index.vue@@ -1,5 +1,5 @@<script setup lang="ts">-const { mdAndUp, smAndDown } = useDisplay()+const { mdAndUp, smAndDown } = useVDisplay()definePageMeta({layout: 'website',diff --git a/web/app/pages/blog/send-bulk-sms-from-csv-file-with-no-code.vue b/web/app/pages/blog/send-bulk-sms-from-csv-file-with-no-code.vueindex 48a2aa4c..9166d40e 100644--- a/web/app/pages/blog/send-bulk-sms-from-csv-file-with-no-code.vue+++ b/web/app/pages/blog/send-bulk-sms-from-csv-file-with-no-code.vue@@ -1,9 +1,7 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'-import { mdiCommentTextMultipleOutline } from '@mdi/js'-const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/blog/send-sms-from-android-phone-with-python.vue b/web/app/pages/blog/send-sms-from-android-phone-with-python.vueindex 72e68853..400f9caa 100644--- a/web/app/pages/blog/send-sms-from-android-phone-with-python.vue+++ b/web/app/pages/blog/send-sms-from-android-phone-with-python.vue@@ -1,7 +1,5 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'--const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/blog/send-sms-when-new-row-is-added-to-google-sheets-using-zapier.vue b/web/app/pages/blog/send-sms-when-new-row-is-added-to-google-sheets-using-zapier.vueindex 73214206..e8a3d9b1 100644--- a/web/app/pages/blog/send-sms-when-new-row-is-added-to-google-sheets-using-zapier.vue+++ b/web/app/pages/blog/send-sms-when-new-row-is-added-to-google-sheets-using-zapier.vue@@ -1,7 +1,5 @@<script setup lang="ts">-import { useDisplay } from 'vuetify'--const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()definePageMeta({ layout: 'website' })diff --git a/web/app/pages/bulk-messages/index.vue b/web/app/pages/bulk-messages/index.vueindex 26a0253c..b25c64c0 100644--- a/web/app/pages/bulk-messages/index.vue+++ b/web/app/pages/bulk-messages/index.vue@@ -14,7 +14,7 @@ useHead({})const router = useRouter()-const { mdAndUp } = useDisplay()+const { mdAndUp } = useVDisplay()const authStore = useAuthStore()const notificationsStore = useNotificationsStore()const { formatTimestamp } = useFilters()diff --git a/web/app/pages/contacts/index.vue b/web/app/pages/contacts/index.vuenew file mode 100644index 00000000..a44865ff--- /dev/null+++ b/web/app/pages/contacts/index.vue@@ -0,0 +1,535 @@+<script setup lang="ts">+import {+ mdiAccountGroupOutline,+ mdiAccountPlus,+ mdiAlertCircleOutline,+ mdiArrowLeft,+ mdiClose,+ mdiDelete,+ mdiFileUpload,+ mdiMagnify,+ mdiPhoneCheck,+ mdiEmailCheckOutline,+ mdiSquareEditOutline,+} from '@mdi/js'+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'+import type { EntitiesContact } from '~~/shared/types/api'+import { useContactsStore } from '~/stores/contacts'+import { useFilters } from '~/composables/useFilters'+import { toApiError } from '~/utils/api-error'++definePageMeta({+ middleware: ['auth'],+})++useHead({+ title: 'Contacts - httpSMS',+})++const contactsStore = useContactsStore()+const { formatPhoneNumber, formatTimestamp, humanizeTimeShort } = useFilters()++const headers = [+ { title: 'Name', key: 'name', sortable: true },+ { title: 'Phone Numbers', key: 'phone_numbers', sortable: false },+ { title: 'Emails', key: 'emails', sortable: false },+ { title: 'Created', key: 'created_at', sortable: false },+ { title: 'Updated', key: 'updated_at', sortable: true },+ { title: 'Actions', key: 'actions', sortable: false, align: 'end' as const },+]++const itemsPerPageOptions = [+ { value: 10, title: '10' },+ { value: 25, title: '25' },+ { value: 50, title: '50' },+ { value: 100, title: '100' },+]++const contactDialog = ref(false)+const deleteDialog = ref(false)+const importDialog = ref(false)+const saving = ref(false)++// Server-driven pagination state for VDataTableServer.+const page = ref(1)+const itemsPerPage = ref(10)+const sortBy = ref<{ key: string; order: 'asc' | 'desc' }[]>([+ { key: 'updated_at', order: 'desc' },+])+// initialLoadComplete gates the table's initial @update:options emit so the+// first fetch is driven by onMounted rather than firing twice on mount.+const initialLoadComplete = ref(false)++const editingContact = ref<EntitiesContact | null>(null)+const pendingDelete = ref<EntitiesContact | null>(null)++const importFile = ref<File | null>(null)+const importErrors = ref<string[]>([])++let searchTimer: ReturnType<typeof setTimeout> | undefined++const searchTerm = computed({+ get: () => contactsStore.search,+ set: (value: string | null) => {+ contactsStore.search = value ?? ''+ },+})++function openAdd() {+ editingContact.value = null+ contactDialog.value = true+}++function openEdit(contact: EntitiesContact) {+ editingContact.value = contact+ contactDialog.value = true+}++function openDelete(contact: EntitiesContact) {+ pendingDelete.value = contact+ deleteDialog.value = true+}++function openImport() {+ importFile.value = null+ importErrors.value = []+ importDialog.value = true+}++function fieldErrorsFromApi(error: unknown): string[] {+ const data = toApiError(error).data?.data+ if (!data || typeof data !== 'object') {+ return []+ }+ return Object.values(data).flat()+}++async function confirmDelete() {+ if (!pendingDelete.value?.id) {+ return+ }+ saving.value = true+ try {+ await contactsStore.deleteContact(pendingDelete.value.id)+ deleteDialog.value = false+ pendingDelete.value = null+ } catch {+ // The store already surfaced the failure via a notification.+ } finally {+ saving.value = false+ }+}++async function submitImport() {+ if (!importFile.value) {+ return+ }+ importErrors.value = []+ saving.value = true+ try {+ await contactsStore.uploadCsv(importFile.value)+ importDialog.value = false+ importFile.value = null+ } catch (error: unknown) {+ // The store already surfaced a toast; keep the row-indexed messages inline+ // so the user can see exactly which CSV rows failed validation.+ importErrors.value = fieldErrorsFromApi(error)+ } finally {+ saving.value = false+ }+}++function fetchContacts() {+ const skip = (page.value - 1) * itemsPerPage.value+ const sort = sortBy.value[0]+ return contactsStore+ .loadContacts({+ force: true,+ skip,+ limit: itemsPerPage.value,+ sortBy: sort?.key === 'name' ? 'name' : 'updated_at',+ sortDescending: sort ? sort.order === 'desc' : true,+ })+ .catch(() => {+ // The store already surfaced the failure via a notification.+ })+}++function onUpdateOptions(options: {+ page: number+ itemsPerPage: number+ sortBy: { key: string; order: 'asc' | 'desc' }[]+}) {+ page.value = options.page+ itemsPerPage.value = options.itemsPerPage+ sortBy.value = options.sortBy.length+ ? options.sortBy+ : [{ key: 'updated_at', order: 'desc' }]++ // Ignore the initial emit fired while the table mounts; onMounted owns the+ // first fetch so the request is not duplicated.+ if (!initialLoadComplete.value) {+ return+ }+ fetchContacts()+}++watch(+ () => contactsStore.search,+ () => {+ if (searchTimer) {+ clearTimeout(searchTimer)+ }+ searchTimer = setTimeout(() => {+ // A new query always resets to the first page. If we are already on+ // page 1 the page ref does not change, so no @update:options fires and+ // we fetch directly; otherwise resetting the page drives the fetch via+ // onUpdateOptions. Either way exactly one request is made.+ if (page.value !== 1) {+ page.value = 1+ } else {+ fetchContacts()+ }+ }, 350)+ },+)++onMounted(() => {+ initialLoadComplete.value = true+ fetchContacts()+})++onBeforeUnmount(() => {+ if (searchTimer) {+ clearTimeout(searchTimer)+ }+})+</script>++<template>+ <VContainer fluid class="px-0 pt-0">+ <VAppBar>+ <VBtn icon to="/threads" aria-label="Back to messages">+ <VIcon :icon="mdiArrowLeft" />+ </VBtn>+ <VToolbarTitle>Contacts</VToolbarTitle>+ <VProgressLinear+ :active="contactsStore.loading"+ :indeterminate="contactsStore.loading"+ color="primary"+ location="bottom"+ absolute+ />+ </VAppBar>++ <VContainer class="pt-0">+ <VRow>+ <VCol cols="12">+ <div class="d-flex align-center">+ <h1 class="text-display-large mb-1">Contacts</h1>+ <VSpacer />+ <div class="mt-12">+ <VBtn+ variant="tonal"+ class="ml-4 mb-4"+ :prepend-icon="mdiFileUpload"+ @click="openImport"+ >+ Import CSV+ </VBtn>+ <VBtn+ class="ml-4 mb-4"+ color="primary"+ variant="flat"+ :prepend-icon="mdiAccountPlus"+ @click="openAdd"+ >+ Add Contact+ </VBtn>+ </div>+ </div>+ <p class="text-medium-emphasis mb-6">+ Use httpSMS as a lightweight CRM by adding your contacts here. Your+ message threads will show contact names instead of phone numbers,+ making conversations easier to recognize and manage. Add contacts+ individually, or fill in our+ <a+ class="text-decoration-none hover:text-decoration-underline"+ href="/templates/httpsms-contacts.csv"+ download+ >CSV template</a+ >+ and upload it to import your contact list in bulk.+ </p>++ <VTextField+ v-model="searchTerm"+ :prepend-inner-icon="mdiMagnify"+ label="Search by name, phone number or email"+ variant="outlined"+ density="compact"+ autocomplete="search-query"+ clearable+ color="primary"+ hide-details+ class="mb-4"+ />++ <VDataTableServer+ v-model:page="page"+ v-model:items-per-page="itemsPerPage"+ v-model:sort-by="sortBy"+ :headers="headers"+ :header-props="{+ class: 'text-uppercase text-medium-emphasis',+ }"+ :items="contactsStore.contacts"+ :items-length="contactsStore.total"+ :loading="contactsStore.loading"+ :items-per-page-options="itemsPerPageOptions"+ item-value="id"+ hover+ loading-text="Loading contacts…"+ @update:options="onUpdateOptions"+ >+ <template #[`item.name`]="{ item }">+ <div class="d-flex align-center py-2">+ <span class="font-weight-medium">{{ item.name }}</span>+ </div>+ </template>++ <template #[`item.phone_numbers`]="{ item }">+ <div+ v-if="item.phone_numbers?.length"+ class="d-flex flex-column ga-1 py-2"+ >+ <div+ v-for="phone in item.phone_numbers ?? []"+ :key="phone"+ class="d-flex"+ >+ <VIcon+ :icon="mdiPhoneCheck"+ size="small"+ color="info"+ class="mr-1 text-medium-emphasis"+ />+ {{ formatPhoneNumber(phone) }}+ </div>+ </div>+ <span v-else class="text-medium-emphasis">—</span>+ </template>++ <template #[`item.emails`]="{ item }">+ <div+ v-if="item.emails?.length"+ class="d-flex flex-column ga-1 py-2"+ >+ <span+ v-for="email in item.emails ?? []"+ :key="email"+ class="d-flex align-center text-body-2"+ >+ <VIcon+ :icon="mdiEmailCheckOutline"+ size="small"+ color="info"+ class="mr-1 text-medium-emphasis"+ />+ {{ email }}+ </span>+ </div>+ <span v-else class="text-medium-emphasis">—</span>+ </template>++ <template #[`item.created_at`]="{ item }">+ <VTooltip :text="formatTimestamp(item.created_at)">+ <template #activator="{ props }">+ <span v-bind="props" class="text-medium-emphasis">+ {{ humanizeTimeShort(item.created_at) }}+ </span>+ </template>+ </VTooltip>+ </template>++ <template #[`item.updated_at`]="{ item }">+ <VTooltip :text="formatTimestamp(item.updated_at)">+ <template #activator="{ props }">+ <span v-bind="props" class="text-medium-emphasis">+ {{ humanizeTimeShort(item.updated_at) }}+ </span>+ </template>+ </VTooltip>+ </template>++ <template #[`item.actions`]="{ item }">+ <div class="d-flex justify-end">+ <VBtn+ :icon="mdiSquareEditOutline"+ variant="text"+ class="mr-2"+ density="comfortable"+ aria-label="Edit contact"+ @click="openEdit(item)"+ />+ <VBtn+ :icon="mdiDelete"+ variant="text"+ density="comfortable"+ color="error"+ aria-label="Delete contact"+ @click="openDelete(item)"+ />+ </div>+ </template>++ <template #no-data>+ <div class="text-center py-12">+ <VIcon+ :icon="mdiAccountGroupOutline"+ size="64"+ class="text-medium-emphasis mb-3"+ />+ <p class="text-title-medium mb-1">+ {{+ searchTerm+ ? 'No contacts match your search'+ : 'No contacts yet'+ }}+ </p>+ <p class="text-medium-emphasis mb-4">+ {{+ searchTerm+ ? 'Try a different name, phone number or email.'+ : 'Add your first contact or import them from a CSV file.'+ }}+ </p>+ <VBtn+ v-if="!searchTerm"+ color="primary"+ variant="flat"+ :prepend-icon="mdiAccountPlus"+ @click="openAdd"+ >+ Add Contact+ </VBtn>+ </div>+ </template>+ </VDataTableServer>+ </VCol>+ </VRow>+ </VContainer>++ <ContactDialog v-model="contactDialog" :contact="editingContact" />++ <!-- Delete contact dialog -->+ <VDialog v-model="deleteDialog" max-width="480" opacity="0.9">+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>Delete Contact</span>+ <VSpacer />+ <VBtn+ :icon="mdiClose"+ variant="text"+ color="warning"+ size="small"+ aria-label="Close dialog"+ @click="deleteDialog = false"+ />+ </VCardTitle>+ <VCardText class="mt-n2 text-medium-emphasis">+ Are you sure you want to delete+ <v-code>{{ pendingDelete?.name }}</v-code+ >? This action cannot be undone.+ </VCardText>+ <VCardActions class="mb-2">+ <VBtn+ color="error"+ variant="flat"+ :prepend-icon="mdiDelete"+ :loading="saving"+ :disabled="saving"+ @click="confirmDelete"+ >+ Delete Contact+ </VBtn>+ <VSpacer />+ <VBtn color="warning" variant="text" @click="deleteDialog = false">+ Close+ </VBtn>+ </VCardActions>+ </VCard>+ </VDialog>++ <!-- Import CSV dialog -->+ <VDialog v-model="importDialog" max-width="600" opacity="0.9">+ <VCard>+ <VCardTitle class="d-flex align-center">+ <span>Import Contacts from CSV</span>+ <VSpacer />+ <VBtn+ :icon="mdiClose"+ variant="text"+ color="warning"+ size="small"+ aria-label="Close dialog"+ @click="importDialog = false"+ />+ </VCardTitle>+ <VCardText>+ <p class="mb-4 mt-n2 text-medium-emphasis">+ Download the+ <a+ class="text-decoration-none hover:text-decoration-underline"+ href="/templates/httpsms-contacts.csv"+ download+ >CSV template</a+ >, fill it in and upload it here. Separate multiple emails or phone+ numbers within a cell using a semicolon (<code>;</code>).+ </p>+ <VFileInput+ v-model="importFile"+ label="CSV file"+ color="primary"+ accept=".csv,text/csv"+ variant="outlined"+ density="comfortable"+ :prepend-icon="mdiFileUpload"+ hide-details="auto"+ />+ <VAlert+ v-if="importErrors.length"+ type="error"+ variant="tonal"+ density="comfortable"+ class="mt-4"+ :icon="mdiAlertCircleOutline"+ >+ <p class="font-weight-medium mb-1">We couldn't import your file:</p>+ <ul class="pl-4 mb-0">+ <li v-for="message in importErrors" :key="message">+ {{ message }}+ </li>+ </ul>+ </VAlert>+ </VCardText>+ <VCardActions class="pb-4">+ <VBtn+ color="primary"+ variant="flat"+ :prepend-icon="mdiFileUpload"+ :loading="saving"+ :disabled="saving || !importFile"+ @click="submitImport"+ >+ Import+ </VBtn>+ <v-spacer />+ <VBtn color="warning" variant="text" @click="importDialog = false">+ Close+ </VBtn>+ </VCardActions>+ </VCard>+ </VDialog>+ </VContainer>+</template>diff --git a/web/app/pages/heartbeats/[id].vue b/web/app/pages/heartbeats/[id].vueindex 8a05d694..3ef5d212 100644--- a/web/app/pages/heartbeats/[id].vue+++ b/web/app/pages/heartbeats/[id].vue@@ -17,7 +17,7 @@ useHead({})const route = useRoute()-const { mdAndDown, mdAndUp, lgAndUp } = useDisplay()+const { mdAndDown, mdAndUp, lgAndUp } = useVDisplay()const authStore = useAuthStore()const phonesStore = usePhonesStore()const { formatPhoneNumber, formatTimestamp } = useFilters()diff --git a/web/app/pages/index.vue b/web/app/pages/index.vueindex 28174569..be30493f 100644--- a/web/app/pages/index.vue+++ b/web/app/pages/index.vue@@ -43,7 +43,7 @@ useSeoMeta({})const config = useRuntimeConfig()-const { lgAndUp, mdAndUp, mdAndDown, md, smAndDown, xl } = useDisplay()+const { lgAndUp, mdAndUp, mdAndDown, md, smAndDown, xl } = useVDisplay()const selectedTab = ref('javascript')const yearlyPricing = ref(false)diff --git a/web/app/pages/messages/index.vue b/web/app/pages/messages/index.vueindex 0a6d53a9..3dd1a544 100644--- a/web/app/pages/messages/index.vue+++ b/web/app/pages/messages/index.vue@@ -17,7 +17,7 @@ useHead({})const router = useRouter()-const { mdAndDown, mdAndUp } = useDisplay()+const { mdAndDown, mdAndUp } = useVDisplay()const notificationsStore = useNotificationsStore()const phonesStore = usePhonesStore()const { useApi } = useApiComposable()diff --git a/web/app/pages/phone-api-keys/index.vue b/web/app/pages/phone-api-keys/index.vueindex 27804cbd..df13c5a6 100644--- a/web/app/pages/phone-api-keys/index.vue+++ b/web/app/pages/phone-api-keys/index.vue@@ -16,7 +16,7 @@ useHead({})const config = useRuntimeConfig()-const { lgAndUp } = useDisplay()+const { lgAndUp } = useVDisplay()const authStore = useAuthStore()const appStore = useAppStore()const phonesStore = usePhonesStore()diff --git a/web/app/pages/search-messages/index.vue b/web/app/pages/search-messages/index.vueindex 925800d7..0e5419f7 100644--- a/web/app/pages/search-messages/index.vue+++ b/web/app/pages/search-messages/index.vue@@ -42,7 +42,7 @@ useHead({const route = useRoute()const config = useRuntimeConfig()-const { mdAndUp, smAndDown, lgAndUp } = useDisplay()+const { mdAndUp, smAndDown, lgAndUp } = useVDisplay()const messagesStore = useMessagesStore()const phonesStore = usePhonesStore()const authStore = useAuthStore()diff --git a/web/app/pages/settings/index.vue b/web/app/pages/settings/index.vueindex 1f381416..63a8c297 100644--- a/web/app/pages/settings/index.vue+++ b/web/app/pages/settings/index.vue@@ -42,7 +42,7 @@ useHead({const config = useRuntimeConfig()const route = useRoute()const router = useRouter()-const { mdAndDown, mdAndUp, lgAndUp, xlAndUp, smAndUp } = useDisplay()+const { mdAndDown, mdAndUp, lgAndUp, xlAndUp, smAndUp } = useVDisplay()const authStore = useAuthStore()const phonesStore = usePhonesStore()const billingStore = useBillingStore()diff --git a/web/app/pages/threads/[id]/index.vue b/web/app/pages/threads/[id]/index.vueindex 73632a64..f933973d 100644--- a/web/app/pages/threads/[id]/index.vue+++ b/web/app/pages/threads/[id]/index.vue@@ -14,12 +14,14 @@ import {mdiAccount,mdiRefresh,mdiContentCopy,+ mdiAccountPlus,+ mdiSquareEditOutline,} from '@mdi/js'import Pusher from 'pusher-js'import type { Channel } from 'pusher-js'import { isValidPhoneNumber } from 'libphonenumber-js'+import { storeToRefs } from 'pinia'import type { EntitiesMessage } from '~~/shared/types/api'-import { startsWithLetter } from '~/utils/filters'definePageMeta({middleware: ['auth'],@@ -32,13 +34,14 @@ useHead({const route = useRoute()const router = useRouter()const config = useRuntimeConfig()-const { lgAndUp, mdAndDown, mdAndUp } = useDisplay()-const { formatPhoneNumber } = useFilters()+const { lgAndUp, mdAndDown, mdAndUp } = useVDisplay()+const { formatPhoneNumber, startsWithLetter } = useFilters()const notificationsStore = useNotificationsStore()const authStore = useAuthStore()const phonesStore = usePhonesStore()const threadsStore = useThreadsStore()const messagesStore = useMessagesStore()+const { currentThread } = storeToRefs(threadsStore)const formMessage = ref('')const submitting = ref(false)@@ -46,6 +49,7 @@ const loadingMessages = ref(false)const hideMessages = ref(true)const messages = ref<EntitiesMessage[]>([])const selectedMenuItem = ref(-1)+const contactDialog = ref(false)const messageBody = ref<HTMLElement | null>(null)const form = ref<{ validate: () => Promise<{ valid: boolean }> } | null>(null)@@ -59,7 +63,7 @@ const formMessageRules = [let webhookChannel: Channel | null = nullconst contactIsPhoneNumber = computed(() => {- const thread = threadsStore.currentThread+ const thread = currentThread.valueif (!thread) return falsereturn isValidPhoneNumber(thread.contact) || !isNaN(Number(thread.contact))})@@ -67,7 +71,7 @@ const contactIsPhoneNumber = computed(() => {const messageVisibility = computed(() =>hideMessages.value ? 'hidden' : 'visible',)-const contact = computed(() => threadsStore.currentThread?.contact ?? '')+const contact = computed(() => currentThread.value?.contact ?? '')function isMT(message: EntitiesMessage): boolean {return message.type === 'mobile-terminated'@@ -104,6 +108,18 @@ function formatAttachmentName(url: string): string {return url}+function currentThreadContactTitle(): string {+ const thread = currentThread.value+ if (!thread) return ''+ return (+ thread.contact_details?.name?.trim() || formatPhoneNumber(thread.contact)+ )+}++async function refreshThreadContact() {+ await threadsStore.loadThreads()+}+function scrollToElement() {const el = messageBody.valueif (el) {@@ -155,7 +171,7 @@ async function loadData() {async function archiveThread() {await threadsStore.updateThread({- threadId: threadsStore.currentThread!.id,+ threadId: currentThread.value!.id,isArchived: true,})await router.push('/threads')@@ -163,7 +179,7 @@ async function archiveThread() {async function unArchiveThread() {await threadsStore.updateThread({- threadId: threadsStore.currentThread!.id,+ threadId: currentThread.value!.id,isArchived: false,})await router.push('/threads')@@ -218,7 +234,7 @@ async function sendMessage(event: KeyboardEvent | Event) {submitting.value = trueawait messagesStore.sendMessage({from: phonesStore.owner!,- to: threadsStore.currentThread!.contact,+ to: currentThread.value!.contact,content: formMessage.value,sim: 'DEFAULT',})@@ -267,8 +283,17 @@ onBeforeUnmount(() => {<VBtn v-if="mdAndDown" icon to="/threads"><VIcon :icon="mdiArrowLeft" /></VBtn>- <VToolbarTitle v-if="threadsStore.currentThread">- {{ formatPhoneNumber(threadsStore.currentThread.contact) }}+ <VToolbarTitle v-if="currentThread">+ <VTooltip+ v-if="currentThread.contact_details?.name?.trim()"+ :text="formatPhoneNumber(currentThread.contact)"+ location="bottom"+ >+ <template #activator="{ props }">+ <span v-bind="props">{{ currentThreadContactTitle() }}</span>+ </template>+ </VTooltip>+ <template v-else>{{ currentThreadContactTitle() }}</template></VToolbarTitle><VMenu><template #activator="{ props }">@@ -282,10 +307,25 @@ onBeforeUnmount(() => {:density="mdAndDown ? 'compact' : 'default'"><VListItem- v-if="- threadsStore.currentThread &&- !threadsStore.currentThread.is_archived- "+ v-if="currentThread?.contact_details"+ @click="contactDialog = true"+ >+ <template #prepend>+ <VIcon :icon="mdiSquareEditOutline" />+ </template>+ <VListItemTitle>Edit Contact</VListItemTitle>+ </VListItem>+ <VListItem+ v-else-if="contactIsPhoneNumber"+ @click="contactDialog = true"+ >+ <template #prepend>+ <VIcon :icon="mdiAccountPlus" />+ </template>+ <VListItemTitle>Add Contact</VListItemTitle>+ </VListItem>+ <VListItem+ v-if="currentThread && !currentThread.is_archived"@click.prevent="archiveThread"><template #prepend>@@ -294,10 +334,7 @@ onBeforeUnmount(() => {<VListItemTitle>Archive</VListItemTitle></VListItem><VListItem- v-if="- threadsStore.currentThread &&- threadsStore.currentThread.is_archived- "+ v-if="currentThread && currentThread.is_archived"@click.prevent="unArchiveThread"><template #prepend>@@ -306,8 +343,8 @@ onBeforeUnmount(() => {<VListItemTitle>Unarchive</VListItemTitle></VListItem><VListItem- v-if="threadsStore.currentThread"- @click.prevent="deleteThread(threadsStore.currentThread.id)"+ v-if="currentThread"+ @click.prevent="deleteThread(currentThread.id)"><template #prepend><VIcon :icon="mdiDelete" color="error" />@@ -323,7 +360,7 @@ onBeforeUnmount(() => {color="primary"indeterminate/>- <VContainer v-if="threadsStore.currentThread" class="pa-0">+ <VContainer v-if="currentThread" class="pa-0"><divref="messageBody"class="messages-body no-scrollbar w-100 pl-2"@@ -350,7 +387,7 @@ onBeforeUnmount(() => {'ml-2': !mdAndUp,'ml-4': mdAndUp,}"- :color="threadsStore.currentThread!.color"+ :color="currentThread.color"size="40"><v-icon@@ -568,6 +605,13 @@ onBeforeUnmount(() => {</VFooter></VContainer></div>+ <ContactDialog+ v-model="contactDialog"+ :contact="currentThread?.contact_details"+ :initial-phone-number="currentThread?.contact ?? ''"+ :refresh-contacts="false"+ @saved="refreshThreadContact"+ /></VContainer></template>diff --git a/web/app/pages/threads/index.vue b/web/app/pages/threads/index.vueindex 03bd1ad5..c1698825 100644--- a/web/app/pages/threads/index.vue+++ b/web/app/pages/threads/index.vue@@ -7,7 +7,7 @@ useHead({title: 'Threads - httpSMS',})-const { lgAndUp } = useDisplay()+const { lgAndUp } = useVDisplay()const authStore = useAuthStore()const phonesStore = usePhonesStore()const threadsStore = useThreadsStore()diff --git a/web/app/stores/contacts.ts b/web/app/stores/contacts.tsnew file mode 100644index 00000000..afa798f7--- /dev/null+++ b/web/app/stores/contacts.ts@@ -0,0 +1,263 @@+import { defineStore } from 'pinia'+import { ref } from 'vue'+import type { EntitiesContact } from '~~/shared/types/api'+import { getApiErrorMessage } from '~/utils/api-error'++export interface ContactInput {+ name: string+ emails: string[]+ phone_numbers: string[]+ properties?: Record<string, string>+}++export interface LoadContactsOptions {+ force?: boolean+ skip?: number+ limit?: number+ sortBy?: 'name' | 'updated_at'+ sortDescending?: boolean+}++export interface ContactMutationOptions {+ refresh?: boolean+}++// DEFAULT_LIMIT mirrors the contacts page's initial items-per-page. It is only+// used when a caller (e.g. a mutation refresh) does not specify its own limit.+const DEFAULT_LIMIT = 10++export const useContactsStore = defineStore('contacts', () => {+ const contacts = ref<EntitiesContact[]>([])+ const total = ref(0)+ const loading = ref(false)+ const search = ref('')+ const { apiFetch } = useApi()+ const notificationsStore = useNotificationsStore()+ let loadContactsGeneration = 0++ // The pagination window last requested by the page. Mutation-triggered+ // refreshes reuse it so the user stays on the page they were viewing.+ let currentSkip = 0+ let currentLimit = DEFAULT_LIMIT+ let currentSortBy: 'name' | 'updated_at' = 'updated_at'+ let currentSortDescending = true++ function normalizeOptions(+ options: LoadContactsOptions | boolean,+ ): LoadContactsOptions {+ if (typeof options === 'boolean') {+ return { force: options }+ }+ return options+ }++ async function loadContacts(+ options: LoadContactsOptions | boolean = {},+ ): Promise<void> {+ const {+ force = false,+ skip,+ limit,+ sortBy,+ sortDescending,+ } = normalizeOptions(options)++ if (skip !== undefined) {+ currentSkip = skip+ }+ if (limit !== undefined) {+ currentLimit = limit+ }+ if (sortBy !== undefined) {+ currentSortBy = sortBy+ }+ if (sortDescending !== undefined) {+ currentSortDescending = sortDescending+ }++ if (contacts.value.length > 0 && !force) return++ const generation = ++loadContactsGeneration+ loading.value = true+ try {+ const term = search.value.trim()+ const params: Record<string, string | number | boolean> = {+ skip: currentSkip,+ limit: currentLimit,+ sort_by: currentSortBy,+ sort_descending: currentSortDescending,+ }+ if (term) {+ params.query = term+ }+ const response = await apiFetch<{+ data: EntitiesContact[]+ total?: number+ }>('/v1/contacts', { params })+ if (generation === loadContactsGeneration) {+ contacts.value = response.data ?? []+ total.value = response.total ?? contacts.value.length+ }+ } catch (error: unknown) {+ if (generation !== loadContactsGeneration) {+ return+ }+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while loading contacts'),+ type: 'error',+ })+ throw error+ } finally {+ if (generation === loadContactsGeneration) {+ loading.value = false+ }+ }+ }++ async function saveContacts(+ items: ContactInput | ContactInput[],+ options: ContactMutationOptions = {},+ ): Promise<void> {+ const contactsToSave = Array.isArray(items) ? items : [items]+ const { refresh = true } = options++ loading.value = true+ try {+ try {+ await apiFetch('/v1/contacts', {+ method: 'POST',+ body: contactsToSave,+ })+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while saving contacts'),+ type: 'error',+ })+ throw error+ }++ notificationsStore.addNotification({+ message:+ contactsToSave.length > 1+ ? 'Contacts created successfully'+ : 'Contact created successfully',+ type: 'success',+ })+ if (refresh) {+ await loadContacts(true)+ }+ } finally {+ loading.value = false+ }+ }++ async function updateContact(+ id: string,+ payload: ContactInput,+ options: ContactMutationOptions = {},+ ): Promise<void> {+ const { refresh = true } = options+ loading.value = true+ try {+ try {+ await apiFetch(`/v1/contacts/${id}`, {+ method: 'PUT',+ body: payload,+ })+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while updating contact'),+ type: 'error',+ })+ throw error+ }++ notificationsStore.addNotification({+ message: 'Contact updated',+ type: 'success',+ })+ if (refresh) {+ await loadContacts(true)+ }+ } finally {+ loading.value = false+ }+ }++ async function deleteContact(id: string): Promise<void> {+ loading.value = true+ try {+ await apiFetch(`/v1/contacts/${id}`, { method: 'DELETE' })+ // Invalidate any in-flight load so a stale response cannot resurrect the+ // just-deleted contact. Bumping the generation makes loadContacts skip+ // its assignment (and its finally toggling loading) for the older request.+ loadContactsGeneration+++ contacts.value = contacts.value.filter((contact) => contact.id !== id)+ total.value = Math.max(0, total.value - 1)+ notificationsStore.addNotification({+ message: 'Contact deleted successfully',+ type: 'success',+ })+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while deleting contact'),+ type: 'error',+ })+ throw error+ } finally {+ loading.value = false+ }+ }++ async function uploadCsv(file: File): Promise<void> {+ loading.value = true+ try {+ try {+ const formData = new FormData()+ formData.append('document', file)++ await apiFetch('/v1/contacts/upload', {+ method: 'POST',+ body: formData,+ })+ } catch (error: unknown) {+ notificationsStore.addNotification({+ message: getApiErrorMessage(error, 'Error while importing contacts'),+ type: 'error',+ })+ throw error+ }++ notificationsStore.addNotification({+ message: 'Contacts imported successfully',+ type: 'success',+ })+ await loadContacts(true)+ } finally {+ loading.value = false+ }+ }++ function resetState() {+ loadContactsGeneration+++ contacts.value = []+ total.value = 0+ loading.value = false+ search.value = ''+ currentSkip = 0+ currentLimit = DEFAULT_LIMIT+ }++ return {+ contacts,+ total,+ loading,+ search,+ loadContacts,+ saveContacts,+ updateContact,+ deleteContact,+ uploadCsv,+ resetState,+ }+})diff --git a/web/app/stores/threads.ts b/web/app/stores/threads.tsindex 7e300262..fdc7094e 100644--- a/web/app/stores/threads.ts+++ b/web/app/stores/threads.ts@@ -28,7 +28,19 @@ export const useThreadsStore = defineStore('threads', () => {const index = threads.value.findIndex((thread) => thread.id === updatedThread.id,)- if (index !== -1) threads.value[index] = updatedThread+ if (index !== -1) {+ const existingThread = threads.value[index]+ threads.value[index] = {+ ...updatedThread,+ // Mark-read PUT responses are not contact-enriched; keep the resolved+ // contact so display names do not disappear after the thread updates.+ contact_details:+ updatedThread.contact_details ??+ (updatedThread.contact === existingThread.contact+ ? existingThread.contact_details+ : undefined),+ }+ }}async function loadThreads() {@@ -45,6 +57,7 @@ export const useThreadsStore = defineStore('threads', () => {owner: phonesStore.owner ?? phonesStore.phones[0]?.phone_number,limit: 100,is_archived: archivedThreads.value,+ contacts: true,},},)diff --git a/web/app/utils/filters.ts b/web/app/utils/filters.tsindex 5ed17d17..2592293e 100644--- a/web/app/utils/filters.ts+++ b/web/app/utils/filters.ts@@ -1,4 +1,11 @@-import { intervalToDuration, formatDuration } from 'date-fns'+import {+ intervalToDuration,+ formatDuration,+ differenceInSeconds,+ differenceInMinutes,+ differenceInDays,+ differenceInHours,+} from 'date-fns'import { parsePhoneNumber, isValidPhoneNumber } from 'libphonenumber-js'export function formatPhoneNumber(value: string): string {@@ -103,3 +110,16 @@ export function humanizeTime(value: string): string {export function startsWithLetter(value: string): boolean {return /^[a-zA-Z]/.test(value)}++export function humanizeTimeShort(date: string) {+ const now = new Date()+ const seconds = differenceInSeconds(now, new Date(date))+ const minutes = differenceInMinutes(now, new Date(date))+ const hours = differenceInHours(now, new Date(date))+ const days = differenceInDays(now, new Date(date))++ if (seconds < 60) return 'just now'+ if (minutes < 60) return `${minutes} minute${minutes !== 1 ? 's' : ''} ago`+ if (hours < 24) return `${hours} hour${hours !== 1 ? 's' : ''} ago`+ return `${days} day${days !== 1 ? 's' : ''} ago`+}diff --git a/web/nuxt.config.ts b/web/nuxt.config.tsindex 1ee80e73..c574ce30 100644--- a/web/nuxt.config.ts+++ b/web/nuxt.config.ts@@ -97,6 +97,9 @@ export default defineNuxtConfig({},vuetify: {+ moduleOptions: {+ prefixComposables: true,+ },vuetifyOptions: {theme: {defaultTheme: 'dark',diff --git a/web/public/templates/httpsms-contacts.csv b/web/public/templates/httpsms-contacts.csvnew file mode 100644index 00000000..8ba7c01d--- /dev/null+++ b/web/public/templates/httpsms-contacts.csv@@ -0,0 +1,4 @@+Name,Emails,PhoneNumbers+John Doe,[email protected],+18005550199+Jane Smith,[email protected];[email protected],+18005550100;+18005550111+Acme Support,,+18005550122diff --git a/web/shared/types/api.ts b/web/shared/types/api.tsindex 27e2db11..3f85c4fb 100644--- a/web/shared/types/api.ts+++ b/web/shared/types/api.ts@@ -71,6 +71,24 @@ export interface EntitiesBulkMessage {total: number;}+export interface EntitiesContact {+ /** @example "2022-06-05T14:26:02.302718+03:00" */+ created_at: string;+ /** @example ["[email protected]"] */+ emails: string[];+ /** @example "32343a19-da5e-4b1b-a767-3298a73703cb" */+ id: string;+ /** @example "Alice Smith" */+ name: string;+ /** @example ["+18005550199","+18005550100"] */+ phone_numbers: string[];+ properties: Record<string, string>;+ /** @example "2022-06-05T14:26:02.302718+03:00" */+ updated_at: string;+ /** @example "WB7DRDWrJZRGbYrv2CKGkqbzvqdC" */+ user_id: string;+}+export interface EntitiesDiscord {/** @example "2022-06-05T14:26:02.302718+03:00" */created_at: string;@@ -199,6 +217,8 @@ export interface EntitiesMessageThread {color: string;/** @example "+18005550100" */contact: string;+ /** ContactDetails is resolved at read time and never persisted. */+ contact_details?: EntitiesContact;/** @example "2022-06-05T14:26:09.527976+03:00" */created_at: string;/** @example "32343a19-da5e-4b1b-a767-3298a73703ca" */@@ -332,6 +352,26 @@ export interface EntitiesWebhook {user_id: string;}+export interface RequestsContactItem {+ emails?: string[];+ /** @example "Alice Smith" */+ name: string;+ phone_numbers: string[];+ properties?: Record<string, string>;+}++export interface RequestsContactStoreRequest {+ contacts: RequestsContactItem[];+}++export interface RequestsContactUpdateRequest {+ emails?: string[];+ /** @example "Alice Smith" */+ name: string;+ phone_numbers: string[];+ properties?: Record<string, string>;+}+export interface RequestsDiscordStore {incoming_channel_id: string;name: string;@@ -625,6 +665,36 @@ export interface ResponsesBulkMessagesResponse {status: string;}+export interface ResponsesContactResponse {+ data: EntitiesContact;+ /** @example "Request handled successfully" */+ message: string;+ /** @example "success" */+ status: string;+}++export interface ResponsesContactsCreatedResponse {+ data: EntitiesContact[];+ /** @example "Request handled successfully" */+ message: string;+ /** @example "success" */+ status: string;+}++export interface ResponsesContactsResponse {+ data: EntitiesContact[];+ /** @example "Request handled successfully" */+ message: string;+ /** @example "success" */+ status: string;+ /**+ * Total is the number of contacts matching the request filter for the+ * user, independent of the pagination skip/limit applied to Data.+ * @example 57+ */+ total: number;+}+export interface ResponsesDiscordResponse {data: EntitiesDiscord;/** @example "Request handled successfully" */