//
//  BGSSpan.h
//  Bugsee
//
//  Copyright © 2026 Bugsee. All rights reserved.
//

#ifndef BGS_SPAN_H
#define BGS_SPAN_H

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * Terminal status of a span. Set explicitly via `setStatus:` /
 * `finishWithStatus:`, or implicitly: `OK` for `finish` (no-arg),
 * `Cancelled` for children that are still live when their parent
 * finishes.
 */
typedef NS_ENUM(NSInteger, BGSSpanStatus) {
    BGSSpanStatusOK = 0,
    BGSSpanStatusError,
    BGSSpanStatusTimeout,
    BGSSpanStatusCancelled,
    BGSSpanStatusDeadlineExceeded,
    BGSSpanStatusUnknown,
} NS_SWIFT_NAME(SpanStatus);

/**
 * A unit of work in the APM span tree. Spans carry an operation name,
 * an optional human-readable description, attributes, and a status. They
 * form a tree rooted at a transaction.
 *
 * Fluent setters return the receiver to support chaining:
 *
 *     [[span setName:@"x"] setAttribute:@"k" value:@"v"];
 *
 * When APM is disabled, `Bugsee.startSpan(...)` and friends return a
 * shared no-op singleton — every call is safe.
 */
NS_SWIFT_NAME(Span)
@protocol BGSSpan <NSObject>

- (id<BGSSpan>)setName:(NSString *)name;
- (id<BGSSpan>)setSpanDescription:(nullable NSString *)description NS_SWIFT_NAME(setDescription(_:));
- (id<BGSSpan>)setAttribute:(NSString *)key value:(id)value NS_SWIFT_NAME(setAttribute(_:value:));
- (id<BGSSpan>)setStatus:(BGSSpanStatus)status;

- (id<BGSSpan>)startChildSpanWithOperation:(NSString *)operation
NS_SWIFT_NAME(startChildSpan(operation:));
- (id<BGSSpan>)startChildSpanWithOperation:(NSString *)operation
                               description:(nullable NSString *)description
NS_SWIFT_NAME(startChildSpan(operation:description:));

@property(readonly) NSString *spanId;
@property(readonly) NSString *traceId;
@property(readonly) BGSSpanStatus status;
@property(readonly) NSString *operation;
@property(readonly, nullable) NSString *spanDescription;
@property(readonly) NSDictionary<NSString *, id> *attributes;
@property(readonly, getter=isFinished) BOOL finished;

- (void)finish;
- (void)finishWithStatus:(BGSSpanStatus)status NS_SWIFT_NAME(finish(status:));

@end

NS_ASSUME_NONNULL_END

#endif // !BGS_SPAN_H
