<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Files\Node;

use DateTimeImmutable;

interface INodeBase extends \JsonSerializable {

	public const JSON_TYPE = 'files.node';
	public const JSON_PROPERTY_TYPE = '@type';
	public const JSON_PROPERTY_IN = 'in';
	public const JSON_PROPERTY_ID = 'id';
	public const JSON_PROPERTY_CREATED_ON = 'createdOn';
	public const JSON_PROPERTY_CREATED_BY = 'createdBy';
	public const JSON_PROPERTY_MODIFIED_ON = 'modifiedOn';
	public const JSON_PROPERTY_MODIFIED_BY = 'modifiedBy';
	public const JSON_PROPERTY_OWNER = 'owner';
	public const JSON_PROPERTY_SIGNATURE = 'signature';
	public const JSON_PROPERTY_LABEL = 'label';

	/**
	 * Unique identifier of the parent node (folder) this node belongs to
	 *
	 * @since 2025.11.01
	 */
	public function in(): string|int|null;

	/**
	 * Unique identifier of this node
	 *
	 * @since 2025.11.01
	 */
	public function id(): string|int;
	
	/**
	 * Node type (collection or entity)
	 *
	 * @since 2025.11.01
	 */
	public function type(): NodeType;

	/**
	 * Creator user ID
	 *
	 * @since 2025.11.01
	 */
	public function createdBy(): string|null;
	
	/**
	 * Creation timestamp
	 *
	 * @since 2025.11.01
	 */
	public function createdOn(): DateTimeImmutable|null;

	/**
	 * Last modifier user ID
	 *
	 * @since 2025.11.01
	 */
	public function modifiedBy(): string|null;

	/**
	 * Last modification timestamp
	 *
	 * @since 2025.11.01
	 */
	public function modifiedOn(): DateTimeImmutable|null;

	/**
	 * Signature/etag for sync and caching
	 *
	 * @since 2025.11.01
	 */
	public function signature(): string|null;

	/**
	 * Check if this node is a collection (folder)
	 *
	 * @since 2025.11.01
	 */
	public function isCollection(): bool;

	/**
	 * Check if this node is an entity (file)
	 *
	 * @since 2025.11.01
	 */
	public function isEntity(): bool;

	/**
	 * Human-readable name/label of this node
	 *
	 * @since 2025.11.01
	 */
	public function getLabel(): string|null;

}