Initial commit

lib/Providers/Personal/Collection.php

@@ -0,0 +1,260 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\PeopleProviderLocal\Providers\Personal;
+
+use KTXF\People\Collection\CollectionContent;
+use KTXF\People\Collection\CollectionPermissions;
+use KTXF\People\Collection\CollectionRoles;
+use KTXF\People\Collection\ICollectionMutable;
+
+class Collection implements ICollectionMutable {
+
+	private ?string $userId = null;
+	private string $providerId = 'default';
+	private string $serviceId = 'personal';
+	private ?string $collectionId = null;
+	private ?string $collectionUuid = null;
+	private ?string $collectionLabel = null;
+	private ?string $collectionDescription = null;
+	private ?int $collectionPriority = null;
+	private ?bool $collectionVisibility = null;
+	private ?string $collectionColor = null;
+	private ?string $collectionCreatedOn = null;
+	private ?string $collectionModifiedOn = null;
+	private bool $collectionEnabled = true;
+	private ?string $collectionSignature = null;
+	private array $collectionPermissions = [
+		CollectionPermissions::View->value => true,
+		CollectionPermissions::Create->value => true,
+		CollectionPermissions::Modify->value => true,
+		CollectionPermissions::Destroy->value => true,
+		CollectionPermissions::Share->value => true,
+	];
+	private array $collectionAttributes = [
+		'roles' => [
+			CollectionRoles::Individual->value => true,
+		],
+		'contents' => [
+			CollectionContent::Individual->value => true,
+			CollectionContent::Organization->value => true,
+			CollectionContent::Group->value => true,
+		],
+	];
+
+	public function jsonSerialize(): mixed {
+		return [
+			self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+			self::JSON_PROPERTY_PROVIDER => $this->providerId,
+			self::JSON_PROPERTY_SERVICE => $this->serviceId,
+			self::JSON_PROPERTY_IN => null,
+			self::JSON_PROPERTY_ID => $this->collectionId,
+			self::JSON_PROPERTY_LABEL => $this->collectionLabel,
+			self::JSON_PROPERTY_DESCRIPTION => $this->collectionDescription,
+			self::JSON_PROPERTY_PRIORITY => $this->collectionPriority,
+			self::JSON_PROPERTY_VISIBILITY => $this->collectionVisibility,
+			self::JSON_PROPERTY_COLOR => $this->collectionColor,
+			self::JSON_PROPERTY_CREATED => $this->collectionCreatedOn,
+			self::JSON_PROPERTY_MODIFIED => $this->collectionModifiedOn,
+			self::JSON_PROPERTY_ENABLED => $this->collectionEnabled,
+			self::JSON_PROPERTY_SIGNATURE => $this->collectionSignature,
+			self::JSON_PROPERTY_PERMISSIONS => [$this->userId => $this->collectionPermissions],
+			self::JSON_PROPERTY_ROLES => $this->collectionAttributes['roles'] ?? [],
+			self::JSON_PROPERTY_CONTENTS => $this->collectionAttributes['contents'] ?? [],
+		];
+	}
+
+	public function jsonDeserialize(array|string $data): static
+	{
+		if (is_string($data)) {
+			$data = json_decode($data, true);
+		}
+
+		$this->collectionId = $data[self::JSON_PROPERTY_ID] ?? null;
+		$this->collectionLabel = $data[self::JSON_PROPERTY_LABEL] ?? null;
+		$this->collectionDescription = $data[self::JSON_PROPERTY_DESCRIPTION] ?? null;
+		$this->collectionPriority = $data[self::JSON_PROPERTY_PRIORITY] ?? null;
+		$this->collectionVisibility = $data[self::JSON_PROPERTY_VISIBILITY] ?? null;
+		$this->collectionColor = $data[self::JSON_PROPERTY_COLOR] ?? null;
+		$this->collectionCreatedOn = $data[self::JSON_PROPERTY_CREATED] ?? null;
+		$this->collectionModifiedOn = $data[self::JSON_PROPERTY_MODIFIED] ?? null;
+		$this->collectionEnabled = $data[self::JSON_PROPERTY_ENABLED] ?? true;
+		$this->collectionSignature = $data[self::JSON_PROPERTY_SIGNATURE] ?? null;	
+
+		return $this;
+	}
+
+	public function fromStore(array|object $data): self
+	{
+		// Convert object to array if needed
+		if (is_object($data)) {
+			$data = (array) $data;
+		}
+
+		// extract properties
+		if (isset($data['cid'])) {
+			$this->collectionId = $data['cid'];
+		} elseif (isset($data['_id'])) {
+			if (is_object($data['_id']) && method_exists($data['_id'], '__toString')) {
+				$this->collectionId = (string) $data['_id'];
+			} elseif (is_array($data['_id']) && isset($data['_id']['$oid'])) {
+				$this->collectionId = $data['_id']['$oid'];
+			} else {
+				$this->collectionId = (string) $data['_id'];
+			}
+		}
+		$this->userId = $data['uid'] ?? null;
+		$this->collectionLabel = $data['label'] ?? null;
+		$this->collectionDescription = $data['description'] ?? null;
+		$this->collectionColor = $data['color'] ?? null;
+		$this->collectionCreatedOn = $data['created'] ?? null;
+		$this->collectionModifiedOn = $data['modified'] ?? null;
+		$this->collectionEnabled = $data['enabled'] ?? true;
+		$this->collectionSignature = isset($data['signature']) ? md5((string)$data['signature']) : null;
+		// Handle BSON array if present
+		if (isset($data['tags'])) {
+			if (is_object($data['tags']) && method_exists($data['tags'], 'bsonSerialize')) {
+				$tags = $data['tags']->bsonSerialize();
+			} else {
+				$tags = $data['tags'] ?? [];
+			}
+		}
+
+		return $this;
+	}
+
+	public function toStore(): array
+	{
+		$data = [
+			'uid' => $this->userId,
+			'uuid' => $this->collectionUuid,
+			'label' => $this->collectionLabel,
+			'description' => $this->collectionDescription,
+			'color' => $this->collectionColor,
+			'created' => $this->collectionCreatedOn,
+			'modified' => $this->collectionModifiedOn,
+			'signature' => $this->collectionSignature,
+			'enabled' => $this->collectionEnabled,
+		];
+
+		// Only include _id if it exists (for updates)
+		if ($this->collectionId !== null) {
+			$data['_id'] = $this->collectionId;
+		}
+
+		return $data;
+	}
+
+	public function in(): null {
+		return null;
+	}
+
+	public function id(): string {
+		return $this->collectionId;
+	}
+
+	public function created(): ?\DateTimeImmutable {
+		return $this->collectionCreatedOn ? new \DateTimeImmutable($this->collectionCreatedOn) : null;
+	}
+
+	public function modified(): ?\DateTimeImmutable {
+		return $this->collectionModifiedOn ? new \DateTimeImmutable($this->collectionModifiedOn) : null;
+	}
+
+	public function attributes(): array {
+		return $this->collectionAttributes;
+	}
+
+	public function uuid(): string {
+		return $this->collectionUuid;
+	}
+
+	public function signature(): ?string {
+		return $this->collectionSignature;
+	}
+
+	public function roles(): array {
+		return $this->collectionAttributes['roles'] ?? [];
+	}
+
+	public function role(CollectionRoles $role): bool {
+		return $this->collectionAttributes['roles'][$role->value] ?? false;
+	}
+
+	public function contents(): array {
+		return $this->collectionAttributes['content'] ?? [];
+	}
+
+	public function contains(CollectionContent $content): bool {
+		return $this->collectionAttributes['content'][$content->value] ?? false;
+	}
+
+	public function getEnabled(): bool {
+		return (bool)$this->collectionEnabled;
+	}
+
+	public function setEnabled(bool $value): self {
+		$this->collectionEnabled = $value;
+		return $this;
+	}
+
+	public function getPermissions(): array {
+		return [$this->userId => $this->collectionPermissions];
+	}
+
+	public function hasPermission(CollectionPermissions $permission): bool {
+		return $this->collectionPermissions[$permission->value] ?? false;
+	}
+
+	public function getLabel(): ?string	{
+		return $this->collectionLabel;
+	}
+
+	public function setLabel(string $value): self {
+		$this->collectionLabel = $value;
+		return $this;
+	}
+
+	public function getDescription(): ?string {
+		return $this->collectionDescription;
+	}
+
+	public function setDescription(?string $value): self {
+		$this->collectionDescription = $value;
+		return $this;
+	}
+
+	public function getPriority(): ?int	{
+		return $this->collectionPriority;
+	}
+
+	public function setPriority(?int $value): self {
+		$this->collectionPriority = $value;
+		return $this;
+	}
+
+	public function getVisibility(): ?bool {
+		return $this->collectionVisibility;
+	}
+
+	public function setVisibility(?bool $value): self {
+		$this->collectionVisibility = $value;
+		return $this;
+	}
+
+	public function getColor(): ?string {
+		return $this->collectionColor;
+	}
+
+	public function setColor(?string $value): self {
+		$this->collectionColor = $value;
+		return $this;
+	}
+
+}

lib/Providers/Personal/Entity.php

@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\PeopleProviderLocal\Providers\Personal;
+
+use DateTimeImmutable;
+use KTXF\People\Entity\IEntityBase;
+use KTXF\People\Entity\IEntityMutable;
+use KTXF\People\Entity\Individual\IndividualObject;
+
+/**
+ * Entity wrapper - contains metadata and EntityData
+ */
+class Entity implements IEntityBase, IEntityMutable {
+
+	// Metadata fields (system-managed)
+	private ?string $entityId = null;
+	private ?string $tenantId = null;
+	private ?string $userId = null;
+	private ?string $collectionId = null;
+	private ?string $createdOn = null;
+	private ?string $modifiedOn = null;
+	private ?string $entitySignature = null;
+	
+	// Entity display properties
+	private ?int $entityPriority = null;
+	private ?bool $entityVisibility = null;
+	private ?string $entityColor = null;
+	private string|array|null $entityData = null;
+
+	public function jsonSerialize(): mixed {
+		return [
+			self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+			self::JSON_PROPERTY_IN => $this->collectionId,
+			self::JSON_PROPERTY_ID => $this->entityId,
+			self::JSON_PROPERTY_DATA => $this->entityData,
+			self::JSON_PROPERTY_SIGNATURE => $this->entitySignature,
+		];
+	}
+
+	public function jsonDeserialize(array|string $data): static
+	{
+		if (is_string($data)) {
+			$data = json_decode($data, true);
+		}
+
+		$this->entityId = $data[self::JSON_PROPERTY_ID] ?? null;
+		$this->collectionId = $data[self::JSON_PROPERTY_IN] ?? null;
+		$this->entitySignature = $data[self::JSON_PROPERTY_SIGNATURE] ?? null;
+		$this->entityData = $data[self::JSON_PROPERTY_DATA] ?? null;
+
+		return $this;
+	}
+
+	public function fromStore(array|object $document): self {
+		// Convert object to array if needed
+		if (is_object($document)) {
+			$document = (array) $document;
+		}
+
+		// Load metadata
+		$this->entityId = $document['eid'] ?? null;
+		$this->tenantId = $document['tid'] ?? null;
+		$this->userId = $document['uid'] ?? null;
+		$this->collectionId = $document['cid'] ?? null;
+		$this->createdOn = $document['createdOn'] ?? null;
+		$this->modifiedOn = $document['modifiedOn'] ?? null;
+		$this->entityData = $document['data'] ?? null;
+		$this->entitySignature = md5(json_encode($this->entityData));
+
+		return $this;
+	}
+
+	public function toStore(): array {
+		$document = [
+			'tid' => $this->tenantId,
+			'uid' => $this->userId,
+			'cid' => $this->collectionId,
+			'eid' => $this->entityId,
+			'createdOn' => $this->createdOn ?? date('c'),
+			'modifiedOn' => date('c'),
+			'data' => $this->entityData,
+		];
+
+		return $document;
+	}
+
+	public function in(): string|int {
+		return $this->collectionId ?? '';
+	}
+
+	public function id(): string|int {
+		return $this->entityId ?? '';
+	}
+
+	public function created(): ?DateTimeImmutable {
+		return $this->createdOn ? new DateTimeImmutable($this->createdOn) : null;
+	}
+
+	public function modified(): ?DateTimeImmutable {
+		return $this->modifiedOn ? new DateTimeImmutable($this->modifiedOn) : null;
+	}
+
+	public function signature(): ?string {
+		return $this->entitySignature;
+	}
+
+	public function getPriority(): ?int {
+		return $this->entityPriority;
+	}
+
+	public function setPriority(?int $value): static {
+		$this->entityPriority = $value;
+		return $this;
+	}
+
+	public function getVisibility(): ?bool {
+		return $this->entityVisibility;
+	}
+
+	public function setVisibility(?bool $value): static {
+		$this->entityVisibility = $value;
+		return $this;
+	}
+
+	public function getColor(): ?string {
+		return $this->entityColor;
+	}
+
+	public function setColor(?string $value): static {
+		$this->entityColor = $value;
+		return $this;
+	}
+
+	public function getDataObject(): IndividualObject|null {
+		return $this->entityData ? (new IndividualObject)->jsonDeserialize($this->entityData) : null;
+	}
+
+	public function setDataObject(IndividualObject $value): static
+	{
+		$this->entityData = $value->jsonSerialize();
+		return $this;
+	}
+
+	public function getDataJson(): array|string|null {
+		return $this->entityData;
+	}
+
+	public function setDataJson(array|string $value): static
+	{
+		$this->entityData = $value;
+		return $this;
+	}
+
+}
+

lib/Providers/Personal/PersonalService.php

@@ -0,0 +1,383 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXM\PeopleProviderLocal\Providers\Personal;
+
+use KTXF\People\Collection\ICollectionMutable;
+use KTXF\People\Entity\IEntityBase;
+use KTXF\People\Service\IServiceBase;
+use KTXF\People\Entity\IEntityMutable;
+use KTXF\People\Service\IServiceCollectionMutable;
+use KTXF\People\Service\IServiceEntityMutable;
+use KTXF\Resource\Exceptions\InvalidParameterException;
+use KTXF\Resource\Filter\Filter;
+use KTXF\Resource\Filter\IFilter;
+use KTXF\Resource\Range\IRange;
+use KTXF\Resource\Range\RangeTally;
+use KTXF\Resource\Range\RangeType;
+use KTXF\Resource\Sort\ISort;
+use KTXF\Resource\Sort\Sort;
+use KTXM\PeopleProviderLocal\Store\Personal\Store;
+
+class PersonalService implements IServiceBase, IServiceCollectionMutable, IServiceEntityMutable {
+
+	protected const SERVICE_ID = 'personal';
+	protected const SERVICE_LABEL = 'Personal Contacts Service';
+	protected const SERVICE_PROVIDER = 'default';
+
+	protected array $serviceCollectionCache = [];
+	protected ?string $serviceTenantId = null;
+	protected ?string $serviceUserId = null;
+	protected ?bool $serviceEnabled = true;
+
+	protected array $serviceAbilities = [
+		self::CAPABILITY_COLLECTION_LIST => true,
+		self::CAPABILITY_COLLECTION_LIST_FILTER => [
+			'id' => 'a:10:64:192',
+			'label' => 's:100:256:771',
+			'description' => 's:100:256:771',
+		],
+		self::CAPABILITY_COLLECTION_LIST_SORT => [
+			'label',
+			'description'
+		],
+		self::CAPABILITY_COLLECTION_EXTANT => true,
+		self::CAPABILITY_COLLECTION_FETCH => true,
+		self::CAPABILITY_COLLECTION_CREATE => true,
+		self::CAPABILITY_COLLECTION_MODIFY => true,
+		self::CAPABILITY_COLLECTION_DESTROY => true,
+		self::CAPABILITY_ENTITY_LIST => true,
+		self::CAPABILITY_ENTITY_LIST_FILTER => [
+			'*' => 's:200:256:771',
+			'uri' => 's:200:256:771',
+			'label' => 's:200:256:771',
+			'phone' => 's:200:256:771',
+			'email' => 's:200:256:771',
+			'location' => 's:200:256:771'
+		],
+		self::CAPABILITY_ENTITY_LIST_SORT => [
+			'label',
+			'phone',
+			'email',
+			'location'
+		],
+		self::CAPABILITY_ENTITY_LIST_RANGE => [
+			'tally' => ['absolute', 'relative']
+		],
+		self::CAPABILITY_ENTITY_DELTA => true,
+		self::CAPABILITY_ENTITY_EXTANT => true,
+		self::CAPABILITY_ENTITY_FETCH => true,
+		self::CAPABILITY_ENTITY_CREATE => true,
+		self::CAPABILITY_ENTITY_MODIFY => true,
+		self::CAPABILITY_ENTITY_DESTROY => true,
+		self::CAPABILITY_ENTITY_COPY => true,
+		self::CAPABILITY_ENTITY_MOVE => true,
+	];
+
+	public function __construct(
+		private Store $store,
+	) {}
+
+	public function jsonSerialize(): mixed {
+		return [
+			self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+			self::JSON_PROPERTY_PROVIDER => self::SERVICE_PROVIDER,
+			self::JSON_PROPERTY_ID => self::SERVICE_ID,
+			self::JSON_PROPERTY_LABEL => self::SERVICE_LABEL,
+			self::JSON_PROPERTY_CAPABILITIES => $this->serviceAbilities,
+			self::JSON_PROPERTY_ENABLED => $this->serviceEnabled,
+		];
+	}
+
+	public function init(string $tenantId, string $userId): self {
+		$this->serviceTenantId = $tenantId;
+		$this->serviceUserId = $userId;
+		return $this;
+	}
+
+	public function capable(string $value): bool {
+		if (isset($this->serviceAbilities[$value])) {
+			return (bool)$this->serviceAbilities[$value];
+		}
+		return false;
+	}
+
+	public function capabilities(): array {
+		return $this->serviceAbilities;
+	}
+
+	public function in(): string{
+		return self::SERVICE_PROVIDER;
+	}
+
+	public function id(): string {
+		return self::SERVICE_ID;
+	}
+
+	public function getLabel(): string {
+		return (string)self::SERVICE_LABEL;
+	}
+
+	public function getEnabled(): bool {
+		return (bool)$this->serviceEnabled;
+	}
+
+	public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array {
+		$entries = $this->store->collectionList($this->serviceTenantId, $this->serviceUserId, $filter, $sort);
+		$this->serviceCollectionCache = $entries;
+		return $entries ?? [];
+	}
+
+	public function collectionListFilter(): Filter {
+		return new Filter($this->serviceAbilities[self::CAPABILITY_COLLECTION_LIST_FILTER] ?? []);
+	}
+
+	public function collectionListSort(): Sort {
+		return new Sort($this->serviceAbilities[self::CAPABILITY_COLLECTION_LIST_SORT] ?? []);
+	}
+
+	public function collectionExtant(string|int $id): bool {
+		// determine if collection is cached
+		if (isset($this->serviceCollectionCache[$id])) {
+			return true;
+		}
+		// retrieve from store
+		return $this->store->collectionExtant($this->serviceTenantId, $this->serviceUserId, $id);
+	}
+
+	public function collectionFetch(string|int $id): ?Collection {
+		// determine if collection is cached
+		if (isset($this->serviceCollectionCache[$id])) {
+			return $this->serviceCollectionCache[$id];
+		}
+		// retrieve from store
+		$collection = $this->store->collectionFetch($this->serviceTenantId, $this->serviceUserId, $id);
+		if ($collection !== null) {
+			$this->serviceCollectionCache[$collection->id()] = $collection;
+			return $collection;
+		}
+		return null;
+	}
+
+	public function collectionFresh(): Collection {
+		return new Collection();
+	}
+
+	public function collectionCreate(string|int $location, ICollectionMutable $collection, array $options): Collection {
+		// convert collection to a native type if needed
+		if (!($collection instanceof Collection)) {
+			$nativeCollection = new Collection();
+			$nativeCollection->jsonDeserialize($collection->jsonSerialize());
+		} else {
+			$nativeCollection = clone $collection;
+		}
+		// create collection in store
+		$result = $this->store->collectionCreate($this->serviceTenantId, $this->serviceUserId, $nativeCollection);
+		$this->serviceCollectionCache[$result->id()] = $result;
+
+		return $result;
+	}
+
+	public function collectionModify(string|int $id, ICollectionMutable $collection): Collection {
+		// validate id
+		if (!is_string($id)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$id' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($id) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$id' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// convert collection to a native type if needed
+		if (!($collection instanceof Collection)) {
+			$nativeCollection = new Collection();
+			$nativeCollection->jsonDeserialize($collection->jsonSerialize());
+		} else {
+			$nativeCollection = clone $collection;
+		}
+		// modify collection in store
+		$result = $this->store->collectionModify($this->serviceTenantId, $this->serviceUserId, $nativeCollection);
+		return $result;
+	}
+
+	public function collectionDestroy(string|int $id): bool {
+		// validate id
+		if (!is_string($id)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$id' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($id) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$id' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// destroy collection in store
+		if ($this->store->collectionDestroyById($this->serviceTenantId, $this->serviceUserId, $id)) {
+			unset($this->serviceCollectionCache[$id]);
+			return true;
+		}
+		return false;
+	}
+
+	public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $options = null): array {
+		// validate id
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// retrieve entities from store
+		$entries = $this->store->entityList($this->serviceTenantId, $this->serviceUserId, $collection, $filter, $sort, $range, $options);
+		return $entries ?? [];
+	}
+
+	
+	public function entityListFilter(): Filter {
+		return new Filter($this->serviceAbilities[self::CAPABILITY_ENTITY_LIST_FILTER] ?? []);
+	}
+
+	public function entityListSort(): Sort {
+		return new Sort($this->serviceAbilities[self::CAPABILITY_ENTITY_LIST_SORT] ?? []);
+	}
+
+	public function entityListRange(RangeType $type): IRange {
+		// validate type
+		if ($type !== RangeType::TALLY) {
+			throw new InvalidParameterException("Invalid: Entity range of type '{$type->value}' is not valid");
+		}
+		return new RangeTally();
+	}
+
+	public function entityExtant(string|int $collection, string|int ...$identifiers): array {
+		// validate id
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// retrieve entity status from store
+		return $this->store->entityExtant($collection, ...$identifiers);
+	}
+
+	public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): array {
+		// validate id
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// retrieve entity delta from store
+		return $this->store->chronicleReminisce($this->serviceTenantId, $this->serviceUserId,$collection, $signature);
+	}
+
+	public function entityFetch(string|int $collection, string|int ...$identifiers): array {
+		// validate id
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// retrieve entity from store
+		$entries = $this->store->entityFetch($this->serviceTenantId, $this->serviceUserId, $collection, ...$identifiers);
+		return $entries ?? [];
+	}
+
+	public function entityFresh(): Entity {
+		return new Entity();
+	}
+
+	public function entityCreate(string|int $collection, IEntityMutable $entity, array $options): Entity {
+		// validate collection identifier
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate collection extant and ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// convert entity to a native type if needed
+		if (!($entity instanceof Entity)) {
+			$nativeEntity = $this->entityFresh();
+			$nativeEntity->jsonDeserialize($entity->jsonSerialize());
+		} else {
+			$nativeEntity = clone $entity;
+		}
+		// create entity in store (store will handle userId and collection)
+		$result = $this->store->entityCreate($this->serviceTenantId, $this->serviceUserId, $collection, $nativeEntity);
+
+		return $result;
+	}
+
+	public function entityModify(string|int $collection, string|int $identifier, IEntityMutable $entity): Entity {
+		// validate collection identifier
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate entity identifier
+		if (!is_string($identifier)) {
+			throw new InvalidParameterException("Invalid: Entity identifier '$identifier' is not valid");
+		}
+		// validate collection extant and ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// validate entity extant and ownership
+		$extant = $this->store->entityExtant($this->serviceTenantId, $this->serviceUserId, $collection, $identifier);
+		if (!isset($extant[$identifier]) || $extant[$identifier] === false) {
+			throw new InvalidParameterException("Invalid: Entity identifier '$identifier' does not exist or does not belong to collection '$collection' or user '{$this->serviceUserId}'");
+		}
+
+		// convert entity to a native type if needed
+		if (!($entity instanceof Entity)) {
+			$nativeEntity = $this->entityFresh();
+			$nativeEntity->jsonDeserialize($entity->jsonSerialize());
+		} else {
+			$nativeEntity = clone $entity;
+		}
+
+		// modify entity in store
+		$result = $this->store->entityModify($this->serviceTenantId, $this->serviceUserId, $collection, $identifier, $nativeEntity);
+
+		return $result;
+	}
+
+	public function entityDestroy(string|int $collection, string|int $identifier): IEntityBase {
+		// validate collection identifier
+		if (!is_string($collection)) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' is not valid");
+		}
+		// validate entity identifier
+		if (!is_string($identifier)) {
+			throw new InvalidParameterException("Invalid: Entity identifier '$identifier' is not valid");
+		}
+		// validate collection extant and ownership
+		if ($this->collectionExtant($collection) === false) {
+			throw new InvalidParameterException("Invalid: Collection identifier '$collection' does not exist or does not belong to user '{$this->serviceUserId}'");
+		}
+		// validate entity extant and ownership
+		$extant = $this->store->entityExtant($this->serviceTenantId, $this->serviceUserId, $collection, $identifier);
+		if (!isset($extant[$identifier]) || $extant[$identifier] === false) {
+			throw new InvalidParameterException("Invalid: Entity identifier '$identifier' does not exist or does not belong to collection '$collection' or user '{$this->serviceUserId}'");
+		}
+		// fetch entity before destruction to return it
+		$entities = $this->store->entityFetch($this->serviceTenantId, $this->serviceUserId, $collection, $identifier);
+		$entity = $entities[$identifier] ?? $this->entityFresh();
+		
+		// destroy entity in store
+		$this->store->entityDestroyById($this->serviceTenantId, $this->serviceUserId, $collection, $identifier);
+		
+		return $entity;
+	}
+	
+}