Add Eloquent model traits

src/Concerns/AutoPublish.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Publish\PublishService;
+
+/**
+ * Trait for Eloquent models that automatically publish to AT Protocol.
+ *
+ * This trait sets up model observers to automatically publish, update,
+ * and unpublish records when the model is created, updated, or deleted.
+ *
+ * Override shouldAutoPublish() and shouldAutoUnpublish() to customize
+ * the conditions under which auto-publishing occurs.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait AutoPublish
+{
+    use PublishesRecords;
+
+    /**
+     * Boot the AutoPublish trait.
+     */
+    public static function bootAutoPublish(): void
+    {
+        static::created(function ($model) {
+            if ($model->shouldAutoPublish()) {
+                app(PublishService::class)->publish($model);
+            }
+        });
+
+        static::updated(function ($model) {
+            if ($model->isPublished() && $model->shouldAutoPublish()) {
+                app(PublishService::class)->update($model);
+            }
+        });
+
+        static::deleted(function ($model) {
+            if ($model->isPublished() && $model->shouldAutoUnpublish()) {
+                app(PublishService::class)->delete($model);
+            }
+        });
+    }
+
+    /**
+     * Determine if the model should be auto-published.
+     *
+     * Override this method to add custom conditions.
+     */
+    public function shouldAutoPublish(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine if the model should be auto-unpublished when deleted.
+     *
+     * Override this method to add custom conditions.
+     */
+    public function shouldAutoUnpublish(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the DID to use for auto-publishing.
+     *
+     * Override this method to customize DID resolution.
+     */
+    public function getAutoPublishDid(): ?string
+    {
+        // Check for did column
+        if (isset($this->did)) {
+            return $this->did;
+        }
+
+        // Check for user relationship with did
+        if (method_exists($this, 'user') && $this->user?->did) {
+            return $this->user->did;
+        }
+
+        // Check for author relationship with did
+        if (method_exists($this, 'author') && $this->author?->did) {
+            return $this->author->did;
+        }
+
+        return null;
+    }
+}

src/Concerns/HasAtpRecord.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Contracts\RecordMapper;
+use SocialDept\AtpParity\MapperRegistry;
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Trait for Eloquent models that map to AT Protocol records.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait HasAtpRecord
+{
+    /**
+     * Get the AT Protocol URI for this model.
+     */
+    public function getAtpUri(): ?string
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Get the AT Protocol CID for this model.
+     */
+    public function getAtpCid(): ?string
+    {
+        $column = config('parity.columns.cid', 'atp_cid');
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Get the DID from the AT Protocol URI.
+     */
+    public function getAtpDid(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://([^/]+)/#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the collection (lexicon NSID) from the AT Protocol URI.
+     */
+    public function getAtpCollection(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://[^/]+/([^/]+)/#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the rkey from the AT Protocol URI.
+     */
+    public function getAtpRkey(): ?string
+    {
+        $uri = $this->getAtpUri();
+
+        if (! $uri) {
+            return null;
+        }
+
+        // at://did:plc:xxx/app.bsky.feed.post/rkey
+        if (preg_match('#^at://[^/]+/[^/]+/([^/]+)$#', $uri, $matches)) {
+            return $matches[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if this model has been synced to AT Protocol.
+     */
+    public function hasAtpRecord(): bool
+    {
+        return $this->getAtpUri() !== null;
+    }
+
+    /**
+     * Get the mapper for this model.
+     */
+    public function getAtpMapper(): ?RecordMapper
+    {
+        return app(MapperRegistry::class)->forModel(static::class);
+    }
+
+    /**
+     * Convert this model to an AT Protocol record DTO.
+     */
+    public function toAtpRecord(): ?Data
+    {
+        $mapper = $this->getAtpMapper();
+
+        if (! $mapper) {
+            return null;
+        }
+
+        return $mapper->toRecord($this);
+    }
+
+    /**
+     * Scope to query models that have been synced to AT Protocol.
+     */
+    public function scopeWithAtpRecord($query)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->whereNotNull($column);
+    }
+
+    /**
+     * Scope to query models that have not been synced to AT Protocol.
+     */
+    public function scopeWithoutAtpRecord($query)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->whereNull($column);
+    }
+
+    /**
+     * Scope to find by AT Protocol URI.
+     */
+    public function scopeWhereAtpUri($query, string $uri)
+    {
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $query->where($column, $uri);
+    }
+}

src/Concerns/HasAtpRelationships.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * Trait for Eloquent models with AT Protocol relationships.
+ *
+ * Provides helpers for defining relationships based on AT Protocol URI references.
+ * Common relationship patterns:
+ *
+ * - reply.parent -> parent_uri column
+ * - reply.root -> root_uri column
+ * - embed.record (quote) -> quoted_uri column
+ * - like.subject -> subject_uri column
+ * - follow.subject -> subject_did column
+ * - repost.subject -> subject_uri column
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait HasAtpRelationships
+{
+    /**
+     * Define an AT Protocol relationship via URI reference.
+     *
+     * This creates a BelongsTo relationship where the foreign key is an AT Protocol URI
+     * stored in the specified column, matched against the related model's atp_uri column.
+     *
+     * Example:
+     * ```php
+     * public function parent(): BelongsTo
+     * {
+     *     return $this->atpBelongsTo(Post::class, 'parent_uri');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpBelongsTo(string $related, string $uriColumn, ?string $ownerKey = null): BelongsTo
+    {
+        $ownerKey = $ownerKey ?? config('parity.columns.uri', 'atp_uri');
+
+        // Create a custom BelongsTo that uses URI matching
+        return $this->belongsTo($related, $uriColumn, $ownerKey);
+    }
+
+    /**
+     * Define an inverse AT Protocol relationship via URI reference.
+     *
+     * This creates a HasMany relationship where related models have a column
+     * containing this model's AT Protocol URI.
+     *
+     * Example:
+     * ```php
+     * public function replies(): HasMany
+     * {
+     *     return $this->atpHasMany(Post::class, 'parent_uri');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpHasMany(string $related, string $foreignKey, ?string $localKey = null): HasMany
+    {
+        $localKey = $localKey ?? config('parity.columns.uri', 'atp_uri');
+
+        return $this->hasMany($related, $foreignKey, $localKey);
+    }
+
+    /**
+     * Define an AT Protocol relationship via DID reference.
+     *
+     * This creates a BelongsTo relationship where the foreign key is a DID
+     * stored in the specified column, matched against a did column on the related model.
+     *
+     * Example:
+     * ```php
+     * public function subject(): BelongsTo
+     * {
+     *     return $this->atpBelongsToByDid(User::class, 'subject_did');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpBelongsToByDid(string $related, string $didColumn, string $ownerKey = 'did'): BelongsTo
+    {
+        return $this->belongsTo($related, $didColumn, $ownerKey);
+    }
+
+    /**
+     * Define an inverse AT Protocol relationship via DID reference.
+     *
+     * Example:
+     * ```php
+     * public function followers(): HasMany
+     * {
+     *     return $this->atpHasManyByDid(Follow::class, 'subject_did');
+     * }
+     * ```
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $related
+     */
+    public function atpHasManyByDid(string $related, string $foreignKey, string $localKey = 'did'): HasMany
+    {
+        return $this->hasMany($related, $foreignKey, $localKey);
+    }
+
+    /**
+     * Get a related model by AT Protocol URI.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelClass
+     * @return \Illuminate\Database\Eloquent\Model|null
+     */
+    public function findByAtpUri(string $modelClass, ?string $uri)
+    {
+        if (! $uri) {
+            return null;
+        }
+
+        $column = config('parity.columns.uri', 'atp_uri');
+
+        return $modelClass::where($column, $uri)->first();
+    }
+}

src/Concerns/PublishesRecords.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpParity\Publish\PublishResult;
+use SocialDept\AtpParity\Publish\PublishService;
+
+/**
+ * Trait for Eloquent models that can be manually published to AT Protocol.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait PublishesRecords
+{
+    use HasAtpRecord;
+
+    /**
+     * Publish this model to AT Protocol.
+     *
+     * If the model has a DID association (via did column or relationship),
+     * it will be used. Otherwise, use publishAs() to specify the DID.
+     */
+    public function publish(): PublishResult
+    {
+        return app(PublishService::class)->publish($this);
+    }
+
+    /**
+     * Publish this model as a specific user.
+     */
+    public function publishAs(string $did): PublishResult
+    {
+        return app(PublishService::class)->publishAs($did, $this);
+    }
+
+    /**
+     * Update the published record on AT Protocol.
+     */
+    public function republish(): PublishResult
+    {
+        return app(PublishService::class)->update($this);
+    }
+
+    /**
+     * Delete the record from AT Protocol.
+     */
+    public function unpublish(): bool
+    {
+        return app(PublishService::class)->delete($this);
+    }
+
+    /**
+     * Check if this model has been published to AT Protocol.
+     */
+    public function isPublished(): bool
+    {
+        return $this->hasAtpRecord();
+    }
+}

src/Concerns/SyncsWithAtp.php

···
+<?php
+
+namespace SocialDept\AtpParity\Concerns;
+
+use SocialDept\AtpSchema\Data\Data;
+
+/**
+ * Trait for models that sync bidirectionally with AT Protocol.
+ *
+ * Extends HasAtpRecord with additional sync tracking and conflict handling.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait SyncsWithAtp
+{
+    use HasAtpRecord;
+
+    /**
+     * Get the column name for tracking the last sync timestamp.
+     */
+    public function getAtpSyncedAtColumn(): string
+    {
+        return 'atp_synced_at';
+    }
+
+    /**
+     * Get the timestamp of the last sync.
+     */
+    public function getAtpSyncedAt(): ?\DateTimeInterface
+    {
+        $column = $this->getAtpSyncedAtColumn();
+
+        return $this->getAttribute($column);
+    }
+
+    /**
+     * Mark the model as synced with the given metadata.
+     */
+    public function markAsSynced(string $uri, string $cid): void
+    {
+        $uriColumn = config('parity.columns.uri', 'atp_uri');
+        $cidColumn = config('parity.columns.cid', 'atp_cid');
+        $syncColumn = $this->getAtpSyncedAtColumn();
+
+        $this->setAttribute($uriColumn, $uri);
+        $this->setAttribute($cidColumn, $cid);
+        $this->setAttribute($syncColumn, now());
+    }
+
+    /**
+     * Check if the model has local changes since last sync.
+     */
+    public function hasLocalChanges(): bool
+    {
+        $syncedAt = $this->getAtpSyncedAt();
+
+        if (! $syncedAt) {
+            return true;
+        }
+
+        $updatedAt = $this->getAttribute('updated_at');
+
+        if (! $updatedAt) {
+            return false;
+        }
+
+        return $updatedAt > $syncedAt;
+    }
+
+    /**
+     * Update the model from a remote record.
+     */
+    public function updateFromRecord(Data $record, string $uri, string $cid): void
+    {
+        $mapper = $this->getAtpMapper();
+
+        if (! $mapper) {
+            return;
+        }
+
+        $mapper->updateModel($this, $record, [
+            'uri' => $uri,
+            'cid' => $cid,
+        ]);
+
+        $this->setAttribute($this->getAtpSyncedAtColumn(), now());
+    }
+
+    /**
+     * Boot the trait.
+     */
+    public static function bootSyncsWithAtp(): void
+    {
+        // Hook into model events if needed
+    }
+}